Ghost Harness API

Returns 200 whenever the process is running. Never touches the database.

Returns 200 only when every dependency needed to serve traffic is reachable. Returns 503 with per-dependency detail otherwise. Load balancers should route on this, not /healthz.

The contract itself, as OpenAPI 3.1 JSON, so a client can generate against the running instance rather than a copy that may have drifted from it.

Unauthenticated: a published interface is not a secret, and requiring a credential to read it would mean a caller needs working auth before it can generate the code that does auth.

Control plane only.

Control plane only. A session token cannot create tenants.

A session token may read only its own tenant. Any other tenantId returns 404, not 403 — a tenant must not be able to probe for the existence of other tenants.

Control plane only. Irreversible. Cancels running runs, revokes all API keys, and destroys tenant data including credentials.

Metadata only. Nothing in this response can reconstruct a key, which is what makes listing safe to expose at all. Revoked keys are included, so an audit can see what once existed.

Returns the key in plaintext. This is the only response that will ever contain it: Ghost stores a hash and a display prefix, so a key that is lost must be revoked and replaced rather than recovered.

Control-plane only. A tenant cannot mint its own keys — a stolen key would otherwise be able to issue itself a replacement and survive the revocation of the key that was noticed.

expires_at is optional and must be in the future. A key that expires gives runs started with it a credential horizon: past it the agent stops taking new actions and the run suspends as awaiting_token_refresh instead of failing.

Takes effect on the next request. The row is marked rather than deleted, so an audit of what could have made a given call survives the revocation.

Idempotent: revoking an already-revoked key reports the key as it stands rather than erroring, because "ensure this key cannot be used" is satisfied either way.

Fails with 409 if the agent has running or suspended runs. Cancel them first.

Title and archived state only. Message history is immutable.

Deletes the session and its messages. Fails with 409 if a run is currently active or suspended.

Message egress. Chronological, oldest first.

Message ingress. The content is treated as data throughout: it is never interpolated into a position where the model can read it as an instruction, regardless of what it contains.

Fails with 409 if the session already has an active or suspended run. One run per session at a time.

Server-sent events for the streaming response mode. Emits the run's history from after_seq and then streams live until the run reaches a terminal state, at which point the server closes the connection.

Each SSE data: frame is one JSON-encoded RunEvent. Reconnect with after_seq set to the last seq you processed; events are durable and replayable, so no events are lost across a reconnect.

A terminal event is always emitted — complete, error, cancelled, or awaiting_approval. Clients should treat connection close without a terminal event as a transport failure and reconnect.

Valid only while the run is awaiting_approval; any other status returns 409.

Approving executes the pending tool and resumes the loop. Denying feeds the refusal back to the model as the tool's result, so it can acknowledge and stop rather than silently retrying.

Returns the resumed run. In sync mode the call blocks until the resumed run reaches a terminal state.

Valid only while the run is awaiting_token_refresh; any other status returns 409. Use POST /v1/runs/{runId}/approval for the approval case.

Carry a fresh, unexpired TenantApiKey on the request. Ghost validates it, checks its tenant claim matches the run's tenant, and continues the loop from where it paused. The run's accumulated state, turn count, and usage are preserved — this is a continuation, not a retry.

There is no request body: the credential in the header is the entire input.

Requests cancellation of a queued, running, or suspended run. Cancellation is cooperative: an in-flight tool call is allowed to finish, so the run may take a moment to reach cancelled. Work already performed is still metered.

Cancelling an already-terminal run returns 409.

The effective allowlist: the intersection of the tenant's enabled tools and this agent's grants. This is the authoritative answer to "can this agent call X" and is enforced at dispatch, not only at prompt assembly.

Full replacement, not a merge. Names not present in the tenant's tool registry are rejected with 422.

The tenant's tool registry. Every descriptor declares its owner (who defined it) and executor (what runs it) separately, so callers do not infer routing from naming conventions.

Runs one tool outside any agent loop, using the calling tenant's credentials. Useful for testing a connection and for products that want Ghost's tool layer without its reasoning layer.

The tool must be on the tenant's allowlist, and on the agent's allowlist when agent_id is supplied. Direct invocation is metered like any other tool call.

Per-tenant accounting over a time window. Covers tokens, wall-clock seconds, and billable actions. When the tenant's allowance is exhausted, cost-bearing endpoints return 402 and in-flight runs are suspended by the circuit breaker.

Metadata only — nothing here can reconstruct a key. Revoked keys are included so an operator can see what once existed.

The self-service counterpart to POST /v1/tenants/{tenantId}/keys. Same result, different credential: this one is authorised by an operator's signed-in session rather than by the control plane, and it takes no tenant id — the tenant comes from the session.

A UserJwt only. Deliberately NOT callable with a TenantApiKey: the reason key management is privileged is that a *stolen key* must not be able to issue itself a replacement and outlive the revocation of the key that was noticed. A session is a different credential class, so allowing it here changes nothing about that threat — allowing a tenant key would reopen it.

As with the control-plane route, the plaintext appears in this response and nowhere else.

Takes effect on the next request. Idempotent: revoking an already-revoked key reports it as it stands rather than erroring.

A key belonging to another tenant reports 404 rather than 403, so the endpoint cannot be used to discover which key ids exist.

Everything the console's billing view needs in one read: the current balance, whether the spend breaker is open, what can be bought, and what has been paid for so far.

mode reports which Stripe account this deployment is wired to, or null when none is configured. A client should treat null as "purchasing is unavailable here" rather than offering a button that cannot work.

A UserJwt only. Purchasing is an act by a person, and a credential that could buy credits would turn a leaked key into a bill.

Creates a Stripe Checkout Session for one credit pack and returns the URL to send the buyer to.

This does not grant credits. It returns a place to pay. Credits are granted only when Stripe reports the payment settled, which arrives as a webhook and may be after the buyer is already back on this site. A client should re-read GET /v1/me/billing on return rather than assuming the balance has moved.

The card is saved against the tenant's Stripe customer for later off-session use. Nothing charges it today.

Where the buyer is returned to is derived from the Origin of this request and checked against Ghost's allowlist — it is not a parameter, so there is no redirect target a caller can choose.

The HTTP exchange log for your tenant, newest first. Distinct from /v1/runs, which reports what agents did: this reports what your integration *sent*, including the calls that never became a run because they were rejected. A 401 from a stale key or a 422 from a malformed body appears here and nowhere else.

Retained for retention_days (30). Older rows are pruned nightly.

Readable with either credential. A tenant key may read its own traffic — that discloses nothing the key does not already have.

Totals over a window, for a console header. Computed over the most recent 5000 calls in the window so one busy tenant cannot make this an unbounded scan.

Stable, machine-readable failure class. Treat unknown members as a generic failure of the response's HTTP status class.

standard agents do work. A meta agent orchestrates other agents in its tenant. Exactly one meta agent exists per tenant and it is created automatically.

user is inbound. agent is the substantive reply. card is a structured payload the client renders as a widget rather than prose.

Where this content came from. Anything other than external_user is machine-originated. Content is wrapped so the model reads it as data regardless of value.

One HTTP exchange against this API.

A key's metadata. Deliberately contains nothing from which the key itself could be reconstructed.

A fixed amount of credits at a fixed price. Packs rather than arbitrary amounts: there is no amount to validate, the ledger stays readable, and a client has something to render without inventing a currency input.

One settled payment. Written by the webhook when money arrived, so a row here means credits were granted — not that a checkout was started.

Terminal states are succeeded, failed, and cancelled.

The two awaiting_* states are suspensions, not endings: the run holds its state indefinitely and survives process restarts. They are separate statuses so a caller can tell "waiting on a human" from "send me a fresh credential" without inspecting anything else.

Why the loop stopped. incomplete means the agent ran out of turns or stated an intention it never carried out — the output is honest about this rather than presenting a promise as a result.

The gated tool call a suspended run is waiting on.

plan, action_start, action_done, and reflect narrate progress and are safe to render as an activity feed. output_delta carries streamed prose. complete, error, cancelled, awaiting_approval, and awaiting_token_refresh are terminal for the stream.

Snake_case for built-in tools. MCP tools are namespaced mcp__<server>__<tool>.

Who defined this tool. core is built into Ghost, composio comes from a connected Composio toolkit, mcp from a registered MCP server, and external is declared by the calling product as an HTTP endpoint.

What runs this tool. Deliberately separate from owner so routing is declared rather than inferred from the tool's name — a naming convention is not a routing table.

http posts the arguments to the URL the owner declared, carrying the caller's session token so the endpoint can authorize the tenant itself.