Sessions

GET /health

Server health check.

Response

200 OK — returns a HealthResponse.

{
  "status": "ok",
  "max_workers": 4,
  "running_workers": 2,
  "total_sessions": 2
}

string

required

Server status. Always "ok" when the server is reachable.

number

required

Maximum number of concurrent worker processes configured on the server.

number

required

Number of worker processes currently executing agent turns.

number

required

Total number of sessions currently held in memory.

A session is created before you send any messages. The server keeps all sessions in memory; they do not persist across server restarts. When --ttl is configured on the server, idle and errored sessions are automatically swept after the TTL period elapses.

Session status

Status	Description
`idle`	Waiting for input. Initial state after creation.
`running`	Currently processing a message. Concurrent sends are rejected with `409`.
`error`	The agent raised an exception. The `error` field contains the message. A session in `error` state can still receive new messages.

POST /sessions

Create a new conversation session. Returns a Location header pointing to the new session URL.

Request body

The request body is optional. Send {} or omit the body entirely to start with an empty session.

ChatMessage[]

Preload the session with an existing conversation history. Each message must include a role ("user" or "assistant") and content string. Omit this field to start with an empty session.

Response

201 Created — returns a SessionResponse and a Location header.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "idle",
  "response": null,
  "error": null
}

string

required

Unique identifier for the session (UUID).

string

required

Current session status: "idle", "running", or "error".

ChatMessage | null

The agent’s most recent response message. null until at least one turn has completed successfully.

string | null

Error message from the most recent failed turn. null when status is not "error".

Errors

Code	Condition
`503`	The server has reached its `--max-sessions` limit.

PUT /sessions/

Create a session with a client-specified ID.

This endpoint requires the server to be started with --allow-custom-ids. Without it, all PUT /sessions/{id} requests return 405.

The request body and response are identical to POST /sessions.

Path parameters

string

required

The UUID you want to assign to this session.

Response

201 Created — returns a SessionResponse and a Location header.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "idle",
  "response": null,
  "error": null
}

Errors

Code	Condition
`400`	The provided session ID is not a valid UUID.
`405`	Custom session IDs are not enabled on this server.
`409`	A session with this ID already exists.
`503`	The server has reached its `--max-sessions` limit.

GET /sessions

List all active sessions.

Response

200 OK — returns a list of SessionSummary objects.

[
  {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_messages": 4,
    "status": "idle"
  }
]

string

required

Unique session identifier.

number

required

Total number of messages in the session’s conversation history.

string

required

Current session status: "idle", "running", or "error".

GET /sessions/

Get session details and the agent’s most recent response. Supports optional long-polling to block until a running turn finishes.

Path parameters

string

required

The session UUID.

Query parameters

boolean

default:"false"

When true, the request blocks until the session is no longer "running".

float

Maximum seconds to wait when wait=true. If the timeout elapses before the turn finishes, the response is returned with status: "running". Omit for an unlimited wait.

Response

200 OK — returns a SessionResponse.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "idle",
  "response": { "role": "assistant", "content": "hi there" },
  "error": null
}

While status is "running", both response and error are null. They are populated only after the turn completes.

Long-poll behavior

Scenario	HTTP status	`status` field
Agent finished successfully	`200`	`"idle"`
Agent raised an exception	`200`	`"error"`
Timeout elapsed before completion	`200`	`"running"`
Session not found or deleted while waiting	`404`	—

Errors

Code	Condition
`404`	Session not found.

DELETE /sessions/

Delete a session and free its resources.

Path parameters

string

required

The session UUID.

Response

204 No Content

It is safe to call this endpoint while a turn is running. The in-progress task is cancelled and the worker process is killed immediately.

Errors

Code	Condition
`404`	Session not found.

CLI

REST API

GET /health

Response

Session status

POST /sessions

Request body

Response

Errors

PUT /sessions/

Path parameters

Response

Errors

GET /sessions

Response

GET /sessions/

Path parameters

Query parameters

Response

Long-poll behavior

Errors

DELETE /sessions/

Path parameters

Response

Errors

​GET /health

​Response

​Session status

​POST /sessions

​Request body

​Response

​Errors

​PUT /sessions/

​Path parameters

​Response

​Errors

​GET /sessions

​Response

​GET /sessions/

​Path parameters

​Query parameters

​Response

​Long-poll behavior

​Errors

​DELETE /sessions/

​Path parameters

​Response

​Errors

GET /health

Response

Session status

POST /sessions

Request body

Response

Errors

PUT /sessions/

Path parameters

Response

Errors

GET /sessions

Response

GET /sessions/

Path parameters

Query parameters

Response

Long-poll behavior

Errors

DELETE /sessions/

Path parameters

Response

Errors