Skip to content

Reference

This page lists the keys the loader accepts. Unknown keys are errors. version must be 1.

Root Keys

Key Required Purpose
version Yes Schema version. Must be 1.
api Yes name and optional description.
server No Bind address, port, timeout, body limit, CORS.
routes No Inline routes.
scenarios No Inline scenarios.
state No Inline collections and values.
include No routes, scenarios, and state file lists.
runtime No Scenario, persistence, history, unmatched, delay.
management No Localhost control port.

At least one route must exist after includes.

api.name must be a non-empty string without ://, /, :, or a space.

Server Defaults

Property Default Purpose
host 127.0.0.1 Bind address. 0.0.0.0 is explicit.
port 8080 API port. 0 asks for a free port.
request_timeout 30 Seconds before a wait becomes 504.
max_request_body 1048576 Largest accepted body, in bytes.
cors.enabled false Add open CORS headers when true.

--host, --port, and --management-port override the file for that process. --scenario overrides runtime.scenario.

Management Defaults

Property Default Purpose
enabled true Open the control port.
host 127.0.0.1 127.0.0.1, localhost, or ::1 only.
port 8081 Control port.

Route Keys

Key Required Purpose
id Yes Stable route id. Unique in the project.
method Yes GET POST PUT PATCH DELETE HEAD OPTIONS.
path Yes Path pattern. {name} captures one segment.
priority No Higher values match first. Default 0.
match No Extra query and header conditions.
response One of three Static or templated response.
sequence One of three Ordered responses.
action One of three State operation.
behaviour No delay_ms and failure_status.
after_sequence No repeat_last, loop, or error.
exhaustion No Response used when after_sequence is error.

Exactly one of response, sequence, and action is required.

Match Keys

Key Match Rule
query Name and exact value. The value may be one of several.
query_present The query name is present.
headers Header name, exact value.
headers_present The header name is present.

Names are compared without case. Header values are exact. Every listed condition must match.

Response Keys

Key Purpose
status Integer from 100 to 599. Default 200.
json JSON body. Templates are rendered.
text Text body. Templates are rendered.
file Fixture path inside the project.
template true renders a text or JSON fixture.
headers Extra response headers.

Use at most one of json, text, and file. Statuses 1xx, 204, and 304, and every HEAD response, are sent with an empty body.

Action Types

Type Success Other Results
collection.list 200 and an array
collection.get 200 and the record 404 when the key is missing
collection.create 201 and the object 400 bad input, 409 duplicate key
collection.update 200 and the record 400 bad input, 404 missing key
collection.delete 204 and an empty body 404 when the key is missing
state.get 200 and the value
state.set 200 and {"updated": name}

status on the action replaces the success status. key selects the record for get, update, and delete. input is required for collection.create and is the new value for state.set. merge: true on update keeps fields you do not send.

Sequence Policies

Policy Behaviour
repeat_last Keep returning the last response. This is the default.
loop Start again at the first response.
error Return exhaustion after the last response.

The default exhaustion response is status 410 and {"error":"Sequence exhausted"}.

State Forms

Form Meaning
Non-empty list of objects with id Collection. The key is id.
{type: collection, key, records} Collection. records may be empty.
{type: value, value} One stored value.
Any other JSON value A value stored under that name.

Duplicate collection names and duplicate value names are errors.

Runtime Keys

Key Default Purpose
scenario normal Active scenario id.
state.persistence memory memory or sqlite.
state.path .ghostport/state.sqlite SQLite file when persistence is sqlite.
history.enabled true Record requests.
history.max_entries 1000 Oldest entries fall away.
history.capture_bodies true Store request bodies.
history.max_body_bytes 65536 Body capture limit.
history.redact_fields empty JSON object keys stored as [redacted].
unmatched 404 {"error":"Not Found"} Response when no route matches.
behaviour.default_delay_ms 0 Delay used when a route omits delay_ms.
behaviour.random_seed omitted Stored. It does not change responses.

Management Endpoints

Method and Path Body Result
GET /status API name, scenario, route count, persistence.
GET /scenario The active scenario.
PUT /scenario {"id":"..."} Switch scenario. POST does the same.
POST /scenario/reset Restore runtime.scenario.
GET /state Collections and values.
POST /state/reset Restore the initial state and sequence counters.
POST /sequence/reset {} or {"route":"id"} Clear one sequence or all sequences.
GET /history {"entries":[...]}
GET /history/{id} One entry, or 404.
DELETE /history Delete the recorded requests.
GET /config The resolved project.

An unknown scenario id or route id returns 400 and {"error":"..."}.

History Fields

Field Contents
request_id Unique id.
timestamp Arrival time.
method HTTP method.
path URL path.
query Query parameters.
headers Request headers after redaction.
body Captured body, or null.
body_truncated true when the capture hit the limit.
route Matched route id, or null.
scenario Active scenario id.
status Response status.
duration_ms Time spent in the engine.
error Template or internal error, or null.

These header names are always redacted: Authorization, Cookie, Set-Cookie, X-Api-Key, Proxy-Authorization.

Template Language

A template is {{ path | filter }}. The path is one or more dot-separated names. A whole-value template keeps the JSON type. Mixed text becomes a string.

Filter Result
int Integer from a string or number.
float Floating point number.
str String. null becomes an empty string.
default(literal) The JSON literal when the path is missing.

default accepts one JSON literal, such as false, 0, null, or "normal". There is no list index and no arithmetic.

Context names are path, query, headers, body, state, and scenario.

Exit Codes

Code Meaning
0 The command finished.
1 An operational or system error.
2 A usage or configuration error.
130 The server was stopped with Ctrl-C.

The Python API

from lupaxa.ghostport import ApiEngine, load_project

project = load_project("samples/hello-api")
engine = ApiEngine(project)

load_project raises ConfigError. Its messages list holds every independent error. ApiEngine.handle accepts one request and returns one response without opening a socket. set_scenario, reset_scenario, reset_state, and reset_sequence are the same operations as the management routes.