HTTP reference

When the ReAct graph is served with an http_server block, the agent exposes a native HTTP API under /v1. These endpoints are specific to the ReAct graph. The API is session-based: a session is the durable conversation boundary, and a run is one execution of the graph within a session. Messages, runs, and state are persisted so a client can inspect them later without keeping the original stream open.

This page describes the conventions shared by every endpoint. The endpoints themselves are grouped by resource on their own pages.

Endpoints

• Sessions: create, find, read, and delete sessions.
• Messages: create, find, read, and delete messages.
• Runs: start, stream, cancel, reattach to, list, and read runs.
• Checkpoints: find checkpoints.
• Types: the named object types shared across the endpoints.

Conventions

Tenancy

Requests may include an X-Tenant-ID header to scope the data to a tenant. When the header is absent, the agent uses the default tenant configured by default_tenant_id in the runtime block.

curl http://localhost:8080/v1/sessions \
  -H "X-Tenant-ID: acme"

Pagination

List endpoints are cursor-paginated. They accept these query parameters:

List responses share the same envelope:

Errors

The API uses standard HTTP status codes. Error responses carry a JSON body in one of two shapes. A generic error reports a code and a message:

{ "code": 404001, "message": "Session not found" }

A validation error reports the failing fields instead of a single message:

{
  "code": 422000,
  "fields": [
    {
      "field": "per_page",
      "errors": [
        { "code": "range", "message": "must be between 1 and 1000", "params": { "min": 1, "max": 1000 } }
      ]
    }
  ]
}

Each entry in fields has a field name and a list of errors, where each error has a code string, an optional human-readable message, and an optional params object with details about the failed rule.

The numeric code encodes the HTTP status: it is the status multiplied by 1000 plus a sub-index, so the HTTP status is code / 1000. For example 404001 and 404002 are both 404 responses with distinct causes, validation errors start at 422000, and internal server errors start at 500000.

Server-Sent Events

The attached run endpoint, POST /v1/runs, streams run events as Server-Sent Events while it starts and executes the run. The reattach endpoint, GET /v1/runs/{run_id}/events, opens a new Server-Sent Events stream to a run that is already executing.

Each event is a text frame with an event line naming the event kind and a data line carrying the JSON payload. An empty line separates consecutive events. The event kinds are documented under Runs.

Disconnect behavior depends on the endpoint. Dropping the original POST /v1/runs stream cancels the attached run. Dropping a GET /v1/runs/{run_id}/events stream only closes that observer; it does not cancel the run. Reattach streams are live-only and do not replay events produced before the stream was opened.