Ghost Harness API

Ghost signs an attribution header onto every outbound MCP call: Ghost-Caller-Identity: <compact JWS>, EdDSA over Ed25519, with kid in the JOSE header. This endpoint publishes the public halves so your MCP server can verify it. Unauthenticated, because a verifier has to reach it before it can trust anything, and its contents are public by construction.

Claims: iss, aud (the server slug the call is going to), iat, exp (120s after iat), tenant_id, agent_id, session_id, run_id.

Attribution, not authorisation. The header never widens what a caller may reach — scope is the credential, and the credential alone. There is deliberately nothing in the claim set a server could mistake for permission: no scopes, no grants, no tool list. If the header and the token disagree about who is calling, reject; do not believe either.

keys is empty when no signing key is configured, in which case no header is sent at all. That is the default, and it is a truthful "nothing here signs" rather than a 404 a client would special-case.

Rotation adds a key at the front and publishes every public half, so a token signed a minute before a rotation still verifies. Poll this rather than pinning a key.

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.

Also where the approval callback is configured. Setting approval_webhook_url returns approval_webhook_secret in this response and in no other — see the field's own description for the minting rule.

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.

One-shot convenience over sessions + messages for platforms housing automations behind an agent. Without session_id this opens a fresh session for the agent and asks in it; with one it continues that session (which must belong to this agent).

mode: stream returns the run's SSE event stream directly — the same frames GET /v1/runs/{runId}/events sends. async/sync return the run like the messages endpoint does. All ingress gates apply identically: this is a shorter path to the same run, not a second loop.

Structured read of one agent's automations (workflow_artifact cards). Newest version per workflow, archived hidden unless include_archived=true.

The full graph — every step with its prompt, tool binding and judge, plus edges and the last test result. Send the revised graph to the agent (ask) to change it.

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.

With mode: "record" this appends to the transcript and returns 201 with a Message. Nothing below applies to a record: it starts no run, so there is nothing to conflict with and nothing to queue behind. See the field's own description.

Otherwise it starts a run, and:

Fails with 409 if the session already has an active or suspended run. One run per session at a time. There is no queue behind the 409: buffer the message yourself and re-post once the run settles.

Fails with 429 if the tenant already has its maximum number of runs in flight across all sessions. This is a concurrency ceiling rather than a request-rate window, so Retry-After is a hint — a slot frees when one of your runs finishes. The 409 is checked first, so a busy session always reports as a session conflict rather than as back-pressure.

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.

The body is {"decision": "approve"} or {"decision": "deny"}. There is no boolean form — {"approved": false} is a 422.

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. Both decisions return it as queued in the default async mode, including deny: a denial still runs a turn, so the run is not terminal when this call returns and you must poll GET /v1/runs/{runId} or watch the event stream for the settled state. Use mode: "sync" to block until it settles instead.

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.

Grants only. Every entry here is granted, so enabled is always true. The tenant's full catalogue — what you *could* grant — is GET /v1/tools. Build a PUT body from this endpoint, never from the catalogue: the PUT is a full replacement, so a body built by unioning catalogue names grants that agent everything the tenant has, including other integrator workspaces' tools.

Not paged. next_cursor is present and always null so one pagination loop is correct against every list endpoint in this API.

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

Replacement means an omitted tool is revoked, including the agent's built-ins, and the call returns 200 either way. To add one tool, read GET /v1/agents/{agentId}/tools, append, and send the whole list back.

The response is the same grants-only shape the GET returns, so "what is on now" is one document whichever verb asked. It may contain more than you sent: Composio grants are per toolkit, so naming one tool of a toolkit grants the toolkit, and the response shows that rather than hiding it.

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.

Registers a streamable-HTTP MCP endpoint and reads its tool catalogue immediately, so a bad URL or credential is reported now rather than when an agent first tries to use a tool.

A sync failure does not fail this request. The registration is real either way and you need its id to retry against — check status and last_error on the response.

url and slug are permanent. Neither can be changed after this call — PATCH /v1/mcp-servers/{serverId} takes the credential and the credential policy only. Changing either means deleting the registration and creating a new one, which revokes every per-agent grant against it and invalidates every session credential keyed on the old slug.

Choose both as if you will never change them, because you will not:

- a hostname you control and expect to keep, not one that embeds a platform or project identifier you might migrate off; - a slug that names the *service*, not whoever registered it first. Ghost signs it as the aud claim of the Ghost-Caller-Identity header, and it is half of every tool name your agents see (mcp__<slug>__<tool>).

This matters more the fewer registrations you have. An integrator sharing one registration across their customers is making this choice exactly once, for everything.

auth_token is write-only. It is never returned by any endpoint; auth reports only whether one is stored.

Cached tools and per-agent grants are removed with it. A run already in flight is unaffected — the tool list offered when a run started is that run's allowlist.

What Ghost read from the server on its last successful sync. The loop reads this cache rather than calling tools/list every turn, so it can be stale — POST .../refresh is how you say the catalogue changed.

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 settlement callback 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 when Stripe confirms 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.

The replay window this run ran under.

A session's transcript is replayed into every run on it, most recent first, up to a cap. The cap is a message count, not a token budget — so the real ceiling on a long conversation is how many messages it has, and a thread that runs for days quietly loses how it started.

That is what this block exists to stop being silent. An agent that has forgotten the beginning of a conversation is otherwise indistinguishable from one choosing to ignore it. Read truncated and re-seed deliberately — the durable fix is to open a fresh session carrying the summary you want kept as context[].

The window is fixed when the run is created, so a run suspended for a day still reports the window it actually used. Ask if you need it raised for your tenant; it is per-tenant configurable, the same way max_concurrent_runs is.

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.

pending — registered, catalogue not yet read. active — last sync succeeded; its tools are offerable. failed — last sync failed; see last_error. The registration is kept so you can fix the endpoint and refresh rather than re-register.

Only the credential and the credential policy. url and slug are deliberately not editable: a URL change repoints every existing grant at a different server while the tool names stay identical, and a slug change silently invalidates every session credential keyed on the old one. Both are a delete and a re-register, where the blast radius is visible.

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.

A grant that is on, not gated for approval, and declares that it writes.

Warned about, not refused: an ungated write is a legitimate configuration and Ghost refusing it would be substituting its judgment for yours. What it should not be is indistinguishable from a working integration, which is what it was.