Base URL and authentication
x-api-key header. A key belongs to
an organization and reaches every project, agent and session in it. Keep it
on the server; the React integration shows how a browser
attaches through your own routes without seeing the key.
Request and response bodies are JSON. Paths below are relative to the base
URL; <p> is a project ID and <r> a memory resource ID.
Errors
Error bodies are{ error: { code, message } }. The code is stable and is
what to branch on; the message is short and safe to show.
A missing key and an unknown route return
{ "error": "<text>" } without a
code.
Sessions
A session is a durable conversation with one deployed agent. It pins the deployment it was created on; see Sessions and turns.Create
The response is
{ session: { id, executionMode, status, createdAt }, deployment }.
The session starts without a turn; send one with the turns route.
Idempotency-Key (at most 256 characters) makes a retry safe. The key
identifies the session within your organization:
- The same key with the same agent, deployment, environment and memory
bindings returns the existing session with
200. - Anything else under that key is
409 idempotency_conflict. The deployment is part of the identity, so after a redeploy the same key conflicts: a session pins its deployment, and new code needs a new session under a new key. 503 memory_admission_unconfirmedmeans the memory grants were not confirmed in time. Retry with the same key; the retry resumes the wait.
400 invalid_environment, 400 invalid_memory_binding,
404 deployment_not_found, 409 deployment_not_promoted (a pinned
deployment is not active in the named environment), 402 insufficient_credits.
Get and list
GET /sessions/<id> returns the session:
GET /sessions returns { sessions }: the fifty most recently updated
sessions of the organization, newest first, in the same shape. There are no
filters or paging parameters; keep your own index of session IDs.
End and interrupt
POST /sessions/<id>/end ends the session. Queued and running turns are
cancelled and memory write access is revoked; do not send further turns to
it. 503 session_end_unconfirmed means the session is ended but the memory
revocation was not acknowledged; retry, or
freeze the document. Ending an
ended session returns it unchanged.
POST /sessions/<id>/interrupt stops the running turn without spending a
model turn. The turn settles as cancelled with reason interrupted, the
runtime is told to stop, and the next queued turn starts. An idle session is
returned unchanged.
Turns
The response is
202 { turnId, status, duplicate } for a new turn and
200 with duplicate: true when the key had already created one. status
is queued or running. Follow the turn in the event log; the response
does not wait for it.
Codes: 400 invalid_turn, 402 insufficient_credits,
409 memory_admission_pending (retry the session creation with its key
first), 409 memory_admission_rejected (the session is ended; create a new
one).
Events
GET /sessions/<id>/events?after=<seq> returns { events }: up to 500
events with seq greater than after, in ascending order. Each event is
{ id, seq, timestamp, sessionId, turnId, type, data }; turnId is absent
on session-level events.
To read a whole log, start at after=0 and repeat with the last seq you
received until a page is empty. A full page means more may follow; read on
without waiting. To follow a live session, keep polling from the last
seq; the CLI’s sessions tail and useAgent do exactly this. The log is
durable, so a consumer that stops can resume from its cursor and miss nothing.
Event types and their data are listed on Session events.
Memory
Document memory belongs to a project and an environment. Every route takes?environment=development or ?environment=production. Bodies, conditional
headers, the document object and the error codes are on
Document memory.
startSessionOnDocument in the
TypeScript SDK does
this create and the session create in one call.
Webhooks
Webhook configuration lives under the project; invocation uses the separate/api/agent-webhooks/<id>/<token> URL described on
Agent webhooks.
identity is header:<name> or body:<json-pointer>. Creating a webhook
for an agent that is not deployed in the environment is
409 webhook_target_unavailable.
Event subscriptions
An event subscription delivers the recorded outcome of turns run by agents in a project to a session in the same project, as a new turn of that session. It is how one agent learns that another finished: a coordinator subscribes to its workers’ outcomes and reasons about them when they arrive. Destinations are sessions only; there is no public HTTPS destination, and this is not the outbound webhooks feature.
A subscription is immutable;
{ subscription } carries id, projectId,
the fields above and createdAt. Codes: 400 invalid_event_subscription,
403 project_scope_violation (the agent is outside the project),
404 destination_session_not_found, 409 destination_session_ended,
404 event_subscription_not_found.
Delivery and receipts
When a selected turn settles, the source session records one delivery per matching subscription and starts a turn on the destination session withsource: "event" input; the receiving agent reads it with useInput()
(Event input). The destination turn’s
idempotency key is <subscription-id>:<event-id>, so a retried delivery
never starts a second turn. Deliveries are retried with backoff and stop
when the subscription is deleted or the destination has ended.
GET /sessions/<id> on the source session lists each turn’s deliveries:
The delivered event names identifiers and the outcome; a completed turn’s
final message is included, bounded to 16 KB. The receiving agent should
treat that text as data about another agent’s work, not as instructions.
Projects, agents and deployments
A project is
{ id, slug, name, environments, agents, createdAt, updatedAt };
agents carries each agent’s id and name. See
Projects and agents for how projects are created and
linked from the CLI.