Skip to main content

​
GET /health

Server health check.

​
Response

200 OK — returns a HealthResponse. 
{
  "status": "ok",
  "max_workers": 4,
  "running_workers": 2,
  "total_sessions": 2
}
​
status
string
required
Server status. Always "ok" when the server is reachable.
​
max_workers
number
required
Maximum number of concurrent worker processes configured on the server.
​
running_workers
number
required
Number of worker processes currently executing agent turns.
​
total_sessions
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

StatusDescription
idleWaiting for input. Initial state after creation.
runningCurrently processing a message. Concurrent sends are rejected with 409.
errorThe 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.
​
state
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
}
​
session_id
string
required
Unique identifier for the session (UUID).
​
status
string
required
Current session status: "idle", "running", or "error".
​
response
ChatMessage | null
The agent’s most recent response message. null until at least one turn has completed successfully.
​
error
string | null
Error message from the most recent failed turn. null when status is not "error".

​
Errors

CodeCondition
503The 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

​
session_id
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

CodeCondition
400The provided session ID is not a valid UUID.
405Custom session IDs are not enabled on this server.
409A session with this ID already exists.
503The 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"
  }
]
​
session_id
string
required
Unique session identifier.
​
total_messages
number
required
Total number of messages in the session’s conversation history.
​
status
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

​
session_id
string
required
The session UUID.

​
Query parameters

​
wait
boolean
default:"false"
When true, the request blocks until the session is no longer "running".
​
timeout
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

ScenarioHTTP statusstatus field
Agent finished successfully200"idle"
Agent raised an exception200"error"
Timeout elapsed before completion200"running"
Session not found or deleted while waiting404—

​
Errors

CodeCondition
404Session not found.

​
DELETE /sessions/

Delete a session and free its resources.

​
Path parameters

​
session_id
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

CodeCondition
404Session not found.