Graph endpoints
In shortReference for the 10xGraph REST endpoints that invoke, stream, stop, and inspect a graph, with request bodies, responses, and auth requirements.
- 14 min read
- 10 sections
- Updated
- v1.0.0
- Markdown
The graph endpoints run your compiled graph over HTTP and WebSocket: invoke it for a complete result, stream it chunk by chunk, stop or repair a thread, and inspect the graph’s nodes, tools, and state schema. This page lists each route with its permission, request body, and response.
Routes sit under /v1/graph, and every response wraps its payload in {"success": true, "data": ...}.
Route summary
| Method | Path | Permission |
|---|---|---|
POST |
/v1/graph/invoke |
graph:invoke |
POST |
/v1/graph/stream |
graph:stream |
POST |
/v1/graph/stop |
graph:stop |
POST |
/v1/graph/fix |
graph:fix |
GET |
/v1/graph |
graph:read |
GET |
/v1/graph/tools |
graph:read |
GET |
/v1/graph:StateSchema |
graph:read |
GET |
/v1/observability/{thread_id} |
graph:read |
WS |
/v1/graph/ws |
graph:stream |
WS |
/v1/graph/live |
graph:stream |
/v1/observability/{thread_id} is documented in Observability and WS /v1/graph/live in Live WebSocket.
POST /v1/graph/invoke
Run the graph and return the complete result when all nodes finish.
Request body:
{
"messages": [
{
"role": "user",
"content": [{"type": "text", "text": "What is the capital of France?"}]
}
]
}content is a list of content blocks, not a plain string. A string gets 422. The example sends no config.thread_id, so the server starts a new thread and returns its id in data.meta.thread_id. Send that id as config.thread_id in the next request to continue the thread. With the default runs.thread_ids of server, naming an id that does not exist answers 404.
| Field | Type | Required | Description |
|---|---|---|---|
messages |
array | yes, unless resume is set |
One or more messages to append to state before invoking. |
resume |
any | no | Answer for a thread paused by interrupt(). The paused node runs again and interrupt() returns this value; null means cancelled. Send it only to resume a paused thread. Nested no deeper than 64 levels by default (MAX_NESTING_DEPTH). |
interrupt_id |
string | no | The id of the interrupt resume answers. Take it from execution_meta.interrupt_data.interrupt.id in the thread state. If the thread is not paused, or is paused at a different interrupt, the request gets 409 before anything runs. Ignored without resume. |
on_busy |
string | no | wait (default) or cancel. What to do when another run is active on the thread (see One run per thread). |
initial_state |
object | no | Initial state for the run. Only keys listed in runs.state_keys are accepted, none by default; built-in fields never are (see input rules below). Nested no deeper than 64 levels by default (MAX_NESTING_DEPTH). |
config |
object | no | Run configuration. Nested no deeper than 64 levels by default (MAX_NESTING_DEPTH). |
config.thread_id |
string | no | Id of an existing thread to continue. Must match ^[A-Za-z0-9._:@-]{1,128}$, else 422. When absent or blank, the server starts a new thread, generates its id and persists it; the id comes back in data.meta.thread_id. With the default runs.thread_ids of server, an id that does not exist answers 404. See runs.thread_ids. |
config.remote_tools |
- | - | Server-owned: dropped from client config, along with user, user_id, collection and _-prefixed keys. A client cannot choose a memory collection; it is ignored, not refused. See Collections. |
recursion_limit |
integer | no | Maximum graph iterations. Default 25, range 1-100. |
response_granularity |
string | no | full, partial, or low. Default low. |
Input rules. The server refuses these with 422:
- A message with role
assistantorsystem. Clients send user messages only. - A
toolmessage that is not made oftool_resultblocks, or that does not answer a remote tool call waiting for a result. - A key in
initial_statethat is not listed inruns.state_keys(an empty list by default).current_nodeneeds listing too. context_summaryorexecution_metaininitial_state. Clients can never write these built-in fields.- A
current_nodeininitial_statethat is not a node in the graph. - A state value whose type does not match the state field. The error names the field.
- An
initial_state,configorresumevalue nested deeper than 64 levels by default (MAX_NESTING_DEPTH). The answer is422with codeVALIDATION_ERROR.
Custom state fields are denied unless the operator lists them in runs.state_keys in 10xgraph.json; only listed keys are accepted. The server replaces any message_id you send with its own. The same rules apply to POST /v1/graph/stream and the WebSocket.
Size limits. At most 500 messages per request, 100 content blocks per message, and 1,000,000 characters of text in total across text blocks. A request over a limit gets 422 with a message that names the limit, in development and production alike. The limits are fixed and apply to invoke, stream and the WebSocket (messages and tool_result), and to PUT /v1/threads/{id}/state context and POST /v1/threads/{id}/messages. AG-UI applies them to the trailing turn.
Messages may carry image and document content blocks referencing an uploaded file_id. Those references are resolved before the graph runs; see Multimodal and vision.
Response:
{
"data": {
"messages": [
{"role": "user", "content": [{"type": "text", "text": "What is the capital of France?"}]},
{"role": "assistant", "content": [{"type": "text", "text": "The capital of France is Paris."}]}
]
},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}data field |
Description |
|---|---|
messages |
Final processed messages from the graph. Always present. |
state |
State from the run, or null. |
context |
Context messages, or null. |
summary |
Summary text, or null. |
meta |
Run metadata such as thread_id, or null. How much is filled in depends on response_granularity. |
One run per thread
The server runs one graph run at a time on a thread. A second run on a busy thread waits up to 30 seconds for the first to finish, then the request is rejected with 409 in the standard error body and a Retry-After: 5 header:
{
"error": {"code": "HTTPException", "message": "thread is busy", "details": []},
"metadata": {"request_id": "...", "timestamp": "...", "message": "thread is busy"}
}On invoke and stream, this answer comes before the response starts. A new thread (no thread_id in the request) is locked as soon as its id exists. The lock is shared across processes when Redis is configured, and per process otherwise. It expires on its own if a worker dies, and is released when the run ends, fails, is cancelled or the client disconnects. /v1/graph/live is not covered.
Set on_busy to "cancel" to stop the running run (the same mechanism as POST /v1/graph/stop) and start the new one. The 30-second wait limit and the 409 still apply if the old run does not stop in time.
On invoke, a run that passes its recursion limit (GraphRecursionError) answers 422, not 500.
Idempotency keys
Send an Idempotency-Key header (1 to 255 printable ASCII characters, else 422) on POST /v1/graph/invoke, POST /v1/graph/stream and POST /v1/ag-ui, or idempotency_key in the WebSocket run frame, so a gateway retry after a timeout does not run the tools twice. The header is opt-in: a request without it behaves as before. The key is scoped to the authenticated user.
| Situation | Answer |
|---|---|
| First request with the key | Runs normally. |
| Same key while that run is still going | 409 with Retry-After: 5. |
| Same key after the run finished, invoke | The stored result, as the first call returned it. |
| Same key after the run finished, stream | The final state line plus the done line, replayed as NDJSON. |
| Same key after the run finished, AG-UI and WebSocket | 409. Their event output is not stored. |
| Same key with a different body | 422. |
| The first run failed | Nothing is stored, so the key can be retried. |
| A result over 1 MiB | Not stored; later requests with the key answer 409. |
A finished run is remembered for IDEMPOTENCY_TTL_SECONDS (default 86400). Records live in Redis when it is configured, otherwise in the process, so without Redis they are per worker. If Redis cannot be reached the request runs without idempotency and a warning is logged.
Resume answers
A resume that does not fit the thread fails before the graph runs:
| Status | Cause |
|---|---|
409 |
interrupt_id was sent and the thread is not paused, or is paused at a different interrupt (INTERRUPT_001). |
409 |
resume was sent to a thread that is not paused at an interrupt() (INTERRUPT_003, NothingToResumeError). |
409 |
A plain new message was sent to a thread that is paused at an interrupt() (INTERRUPT_004, InterruptPendingError). Resume it with resume. |
422 |
The answer fails the interrupt’s response_schema (INTERRUPT_002). |
The schema check supports type, enum, properties, required and items. Other keywords are ignored. A null answer (cancel) is never checked. See Interrupts.
POST /v1/graph/stream
Run the graph and stream one JSON-encoded StreamChunk per line.
Request body: Same as /v1/graph/invoke, including resume, interrupt_id, on_busy and the size limits.
A repeated Idempotency-Key is answered the same way (see Idempotency keys). A busy thread (409, with Retry-After: 5), a run over the per-user cap (429, with Retry-After: 5), a resume that does not fit the thread (409) and a client that left while waiting for a busy thread (499, never read) are answered before the stream starts, as a normal HTTP error. Failures once the stream is running arrive as an error chunk. With MODE=production, the text in an error chunk’s data (reason, error or message) is replaced by the same generic message invoke uses, such as An error occurred in a graph node.; development shows the details. The built-in text for an unexpected tool failure (Tool '<name>' failed with an internal error (reference <id>).) is kept, because it holds no detail.
Response: Content-Type: application/x-ndjson
The body is newline-delimited JSON, not SSE. There are no data: prefixes. Split the body on newlines rather than using EventSource or an SSE client library. While the run is silent, the server sends a blank line every 15 seconds so a proxy’s idle timeout does not cut the connection. Skip empty lines.
{"event": "message", "message": {"role": "assistant", "content": [{"type": "text", "text": "The capital"}]}, "thread_id": "t1", ...}
{"event": "message", "message": {"role": "assistant", "content": [{"type": "text", "text": " of France is Paris."}]}, "thread_id": "t1", ...}
{"event": "updates", "data": {"status": "done"}, "thread_id": "t1", ...}StreamChunk fields
| Field | Type | Description |
|---|---|---|
event |
string |
Chunk discriminator. One of message, state, updates, error. |
message |
object | null |
Populated when event is message. A full Message with a content block list. |
state |
object | null |
Populated when event is state. The current AgentState. |
data |
object | null |
Populated for updates (for example {"status": "done"}) and error (for example {"reason": "..."}). |
thread_id |
string | null |
Thread this chunk belongs to. |
run_id |
string | null |
Run this chunk belongs to. |
metadata |
object | null |
Additional per-chunk metadata. |
timestamp |
number |
UNIX timestamp of chunk creation. |
Tool activity arrives as ordinary message chunks whose content carries tool_call and
tool_result blocks. There is no separate tool_call event type.
A run that is refused because the graph is closing ends with a terminal error chunk whose data has code: "SERVICE_UNAVAILABLE", a reason and retry_after_seconds (the same hint as the HTTP 503 Retry-After). No done chunk follows. Treat it as “retry on another replica”, not as a failed run.
A stream that finishes without an error ends with a terminal updates chunk whose data is {"status": "done"}. A client that waits for it can tell a finished stream from a cut one. If the server shuts down while the stream is open, the stream ends with a final chunk that says the run was interrupted and that the thread is saved: send a new request on the same thread_id to continue.
POST /v1/graph/stop
Cancel an in-progress graph execution.
Request body:
{
"thread_id": "my-thread-1",
"config": {}
}Response:
{
"data": {"ok": true, "running": true},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}The request records a stop flag on the thread, and the running graph checks it between nodes, so the current node finishes first. When nothing is running the call still succeeds, with running: false (reason: "no-state") or ok: false (reason: "no-checkpointer"). Stopping needs a checkpointer. A stop request belongs to the run it targets: starting a new run on the thread does not clear a stop meant for a run that is still going.
GET /v1/graph
Get metadata about the loaded graph: its nodes, edges, and an info block describing how the server is wired.
Response:
{
"data": {
"info": {
"node_count": 2,
"edge_count": 3,
"is_realtime": false,
"checkpointer": true,
"checkpointer_type": "PgCheckpointer",
"publisher": false,
"store": false,
"interrupt_before": null,
"interrupt_after": null,
"context_type": null,
"id_generator": "SnowFlakeIdGenerator",
"id_type": "BIGINT",
"state_type": "AgentState",
"state_fields": ["context", "context_summary"]
},
"nodes": [
{"id": "MAIN", "name": "MAIN"},
{"id": "TOOL", "name": "TOOL"}
],
"edges": [
{"id": "MAIN-TOOL", "source": "MAIN", "target": "TOOL"}
]
},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}info.is_realtime
is_realtime is true when the compiled graph is rooted at a live (realtime) agent. Clients use it to decide which socket to open:
is_realtime |
Use |
|---|---|
false |
POST /v1/graph/invoke, POST /v1/graph/stream, WS /v1/graph/ws |
true |
WS /v1/graph/live |
Connecting to the wrong one is rejected at the handshake with close code 1008, so read this field once at startup and route accordingly.
GET /v1/graph/tools
List the tools exposed by every ToolNode in the graph, grouped by node.
Response:
{
"data": {
"node_count": 1,
"tool_count": 2,
"nodes": [
{
"node_name": "TOOL",
"tool_count": 2,
"tools": [
{
"name": "get_weather",
"description": "Look up the current weather for a city.",
"source": "local",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
},
{
"name": "search_repos",
"description": "Search GitHub repositories.",
"source": "mcp",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}}
}
]
}
]
},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}| Field | Description |
|---|---|
node_count |
Number of ToolNodes in the graph |
tool_count |
Total tools across all tool nodes |
nodes[].node_name |
Name of the tool node in the graph |
nodes[].tools[].source |
local (a Python function on the node), mcp (from a connected MCP server), or remote (declared in 10xgraph.json and executed by a client) |
nodes[].tools[].parameters |
JSON Schema for the tool’s parameters, in OpenAI function-calling shape |
Tool collection is best-effort per node: an MCP server that fails to respond is logged and its node contributes no tools, rather than failing the whole request.
POST /v1/graph/fix
Repair a thread whose history is broken because a run stopped after the model asked for tools but before the results were saved.
The repair works in two steps:
- An assistant message is removed when any of its tool calls has no matching tool result. Calls and results are matched by tool call id.
- Tool result messages whose call no longer exists, including results left over from a message removed in step 1, are then removed. Every remaining result has its call.
If the thread is paused (an interrupt(), a client tool call waiting for its result, or a human-approval pause), the unanswered calls of the latest assistant message are kept, because the pause is waiting on them. Earlier dangling calls are still removed. Messages without tool calls are never touched.
When nothing needs fixing, the response has removed_count: 0 and the state is not written.
Request body:
{
"thread_id": "my-thread-1",
"config": {}
}thread_id is required and must not be blank.
Response:
{
"data": {
"success": true,
"message": "Removed 1 message with unanswered tool calls",
"removed_count": 1,
"state": {}
},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}WS /v1/graph/ws
Turn-based streaming over a WebSocket. Same payloads as POST /v1/graph/stream, but the connection stays open across runs, which is what makes client-side tool execution possible without a second HTTP request.
Always mounted. There is no setting that turns this endpoint off. Concurrent connections are capped (shared by all workers with Redis, per process without) by websocket.max_connections and max_connections_per_user; a refused handshake closes with code 1013.
Authentication. Bearer token via the Authorization header, the 10xgraph-bearer Sec-WebSocket-Protocol (preferred for browsers). A ?token= query parameter is not accepted. Identical to the live socket.
Fresh run. Client sends:
{
"invoke_type": "fresh",
"messages": [{"role": "user", "content": [{"type": "text", "text": "What is the weather in Paris?"}]}],
"config": {"thread_id": "my-thread-1"}
}messages must be non-empty, unless the frame carries resume. A frame may carry idempotency_key (see Idempotency keys); a repeat of the key (while the run is going or after it finished) or a different body with the same key gets an error chunk, and the connection stays open. config.thread_id is optional; omit it, or send "new", to start a new thread. The server picks the id and sends it on each chunk. A thread_id that does not exist gets an error chunk, the same as an unauthorized one, unless runs.thread_ids is client.
Answer an interrupt() pause. A fresh frame accepts resume (any JSON value, null to cancel) and an optional interrupt_id, with the same meaning as on invoke. No messages are needed:
{
"invoke_type": "fresh",
"resume": {"approved": true},
"interrupt_id": "int_abc123...",
"config": {"thread_id": "my-thread-1"}
}Resume after a remote tool call. When the stream contains a remote tool call, the client executes the tool and sends:
{
"invoke_type": "resume",
"tool_result": [{"role": "tool", "content": [{"type": "tool_result", "call_id": "call-abc123", "output": "24 degrees and sunny"}]}],
"config": {"thread_id": "my-thread-1"}
}tool_result must be non-empty and config.thread_id is required, so the server can resume the right checkpoint. Each message must be a tool message of tool_result blocks that answers a pending remote tool call, and call_id must match that call.
Both frames also accept initial_state, recursion_limit, on_busy and response_granularity with the same meaning as POST /v1/graph/invoke, and the same input rules.
Server frames. The server sends StreamChunk JSON messages, identical to the HTTP stream, followed by a terminator:
{"event": "updates", "data": {"status": "done"}}The server does not inspect chunks for tool calls; detecting a remote tool call is the client’s job. invoke_type is used only for validation and logging.
Close codes.
| Code | Meaning |
|---|---|
1000 |
Normal closure |
1008 |
Auth or authorization rejected, or the graph is a live agent (use /v1/graph/live) |
1011 |
Unexpected server error |
1013 |
Rate limit or websocket.max_connections exceeded |
Recoverable problems (an invalid frame, an unauthorized thread_id, a busy thread, a resume that does not match the open interrupt) are sent as an error StreamChunk and the connection stays open for the next request.
GET /v1/graph:StateSchema
Get the JSON schema for the graph’s state class.
Response:
{
"data": {
"type": "object",
"properties": {
"context": {"type": "array"},
"user_id": {"type": "string"}
}
},
"metadata": {"request_id": "...", "timestamp": "...", "message": "OK"}
}Authentication
When auth is configured, all endpoints require an Authorization header:
Authorization: Bearer <token>See Authentication for configuration details.