Conventions and permissions
In shortThe 10xGraph REST API response envelope, HTTP and WebSocket authentication, the endpoint permission table, WebSocket close codes and HTTP status codes.
- 7 min read
- 8 sections
- Updated
- v1.0.0
- Markdown
Every route in the 10xGraph REST API lives under /v1/ (except /ping), returns the same JSON envelope, authenticates with a Bearer token, and is guarded by a resource and action permission pair. This page lists those shared rules, the full permission table, the WebSocket close codes and the HTTP status codes.
Base URL and response envelope
Successful responses wrap the payload in data and add a metadata object with request_id, timestamp and message. Errors raised by the application return error instead, with the same metadata. The details list is empty unless the error carries extra context (validation errors, or the context of a graph or node error outside production).
{
"data": {},
"metadata": {
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-05-23T10:00:00",
"message": "OK"
}
}{
"error": {
"code": "EXPIRED_TOKEN",
"message": "Token has expired, please login again",
"details": []
},
"metadata": {
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-05-23T10:00:00",
"message": "Token has expired, please login again"
}
}Resource ids
Thread, message and memory ids must match ^[A-Za-z0-9._:@-]{1,128}$: 1 to 128 letters, digits and . _ : @ -, with no spaces or slashes. This applies to the thread_id, message_id and memory_id path parameters and to thread_id and config.thread_id in request bodies. Any other id gets 422 with code VALIDATION_ERROR. Ids the server makes itself (Snowflake integers, UUIDs, store memory ids) always fit.
The same rule covers the WebSocket config.thread_id, the thread_id in the /v1/graph/live init frame and the AG-UI threadId (an error frame or 422, code VALIDATION_ERROR).
Request size limits
Client dicts and lists (config, initial_state, resume, metadata, filters, and the bodies of the store and checkpointer routes and WebSocket frames) are capped beside the nesting depth limit (64 levels by default, MAX_NESTING_DEPTH): at most 1000 keys per object, 10000 items per list and 200000 values in all. A body over a cap gets 422 VALIDATION_ERROR. The key, item and value caps are fixed and have no setting.
Idempotency keys
Run routes accept an opt-in Idempotency-Key header so a retried request does not run twice. See Idempotency keys. IDEMPOTENCY_TTL_SECONDS (default 86400) sets how long a finished run is remembered.
Errors from HTTPException (permission denied, not found, empty upload) use the code HTTPException. Request validation failures use VALIDATION_ERROR. Data the database cannot store (a NUL character, a lone surrogate, a number out of range) uses INVALID_REQUEST_DATA. Authentication failures use INVALID_TOKEN, EXPIRED_TOKEN or REVOKED_TOKEN; see the auth error codes. A body over MAX_REQUEST_SIZE uses REQUEST_TOO_LARGE. Three responses come from middleware and do not use this exact shape: the state_conflict 409, 413 and 429 (see HTTP status codes).
Authentication
When auth is configured in 10xgraph.json, every endpoint except /ping needs a Bearer token. Send it as an Authorization header on HTTP routes. WebSocket clients that cannot set headers have two fallbacks, listed here in order of preference.
Authorization: Bearer <token>// Preferred for browsers: the token rides in a request header, not the URL
new WebSocket("ws://host/v1/graph/ws", ["10xgraph-bearer", token]);The server echoes the 10xgraph-bearer sentinel back on accept, which browsers require to complete the handshake. The older agentflow-bearer sentinel is accepted until 2.0. A ?token= query parameter is not accepted: a token in the URL would land in access logs. The subprotocol is read only on WebSocket connections.
If auth is not configured ("auth": null), credentials are not required. Missing, invalid or expired credentials return HTTP 401. A permission failure returns 403. On WebSocket routes both become close code 1008. See authentication for setup.
Permission model
Each endpoint declares one (resource, action) pair. On every request the server calls authorize(identity, "resource:action", resource_id) on your BaseAuth. The default implementation checks the permissions on the caller’s Identity: everything except admin:* when no roles are configured, or what the caller’s roles grant. A missing permission answers 403. A thread, message, memory, file or run that the caller’s reach does not cover answers 404. See authentication and authorization.
Permission reference
The table lists every (resource, action) pair the server enforces. POST /v1/ag-ui exists only when ag_ui.enabled is true in 10xgraph.json, and the /v1/tasks routes only when background tasks are configured.
| Endpoint | Resource | Action |
|---|---|---|
POST /v1/graph/invoke |
graph |
invoke |
POST /v1/graph/stream |
graph |
stream |
POST /v1/ag-ui |
graph |
stream |
WebSocket /v1/graph/ws |
graph |
stream |
WebSocket /v1/graph/live |
graph |
stream |
GET /v1/graph |
graph |
read |
GET /v1/graph/tools |
graph |
read |
GET /v1/observability/{thread_id} |
graph |
read |
GET /v1/graph:StateSchema |
graph |
read |
POST /v1/graph/stop |
graph |
stop |
POST /v1/graph/fix |
graph |
fix |
GET /v1/threads/{id}/state |
threads |
read |
PUT /v1/threads/{id}/state |
threads |
write |
DELETE /v1/threads/{id}/state |
threads |
delete |
GET /v1/threads/{id}/messages |
threads |
read |
GET /v1/threads/{id}/messages/{msg} |
threads |
read |
PUT /v1/threads/{id}/messages/{msg} |
threads |
write |
DELETE /v1/threads/{id}/messages/{msg} |
threads |
delete |
GET /v1/threads |
threads |
read |
GET /v1/threads/{id} |
threads |
read |
DELETE /v1/threads/{id} |
threads |
delete |
POST /v1/store/memories |
store |
write |
POST /v1/store/search |
store |
read |
POST /v1/store/memories/{id} |
store |
read |
POST /v1/store/memories/list |
store |
read |
PUT /v1/store/memories/{id} |
store |
write |
DELETE /v1/store/memories/{id} |
store |
delete |
POST /v1/store/memories/forget |
store |
delete |
POST /v1/files/upload |
files |
upload |
GET /v1/files/{id} |
files |
read |
GET /v1/files/{id}/info |
files |
read |
GET /v1/files/{id}/url |
files |
read |
GET /v1/config/multimodal |
config |
read |
GET /v1/tasks/{id} |
tasks |
read |
POST /v1/tasks/{name} and PATCH /v1/tasks/{id} |
tasks |
trigger |
POST /v1/tasks/{id}/cancel |
tasks |
cancel |
GET /v1/me |
(identity only) | (none) |
GET /ping |
(none) | (none) |
The /ping row is the complete public allowlist. Every other route must carry a RequirePermission guard, and the server refuses to start if one does not.
WebSocket close codes
WebSocket routes report failures with close codes instead of HTTP statuses. 1008 also covers a graph that is on the wrong socket: a realtime graph on /v1/graph/ws, or a turn-based graph on /v1/graph/live.
| Code | Name | When |
|---|---|---|
1000 |
Normal closure | The client disconnected cleanly |
1008 |
Policy violation | Authentication or authorization failed, or the graph type does not match the route |
1011 |
Server error | Unexpected server error |
1013 |
Try again later | Rate limit or connection cap exceeded at the handshake |
HTTP status codes
These are the status codes the server returns. Routes document their own specific causes on their pages.
| Code | When |
|---|---|
200 |
Success |
400 |
Empty file upload, missing filename, or malformed Content-Length |
401 |
Missing, invalid, expired or revoked credentials (INVALID_TOKEN, EXPIRED_TOKEN, REVOKED_TOKEN) |
403 |
Insufficient permissions, or access to a thread you do not own |
404 |
File, thread, message or eval run not found |
409 |
A run on this thread is still active after 30 seconds (message is thread is busy), or a resume does not fit the thread: the interrupt_id does not match, the thread is not paused, or a plain message was sent to a thread paused at an interrupt(). The busy answer carries Retry-After: 5. The same status answers a repeated Idempotency-Key while its run is going (with Retry-After: 5), a finished key on AG-UI or WebSocket, and a stored thread whose node no longer exists (GRAPH_NODE_MISSING_001). Standard error body with code HTTPException. See One run per thread |
409 |
Another run updated the thread while yours was in flight. Body is {"error": "state_conflict", "detail": "...", "thread_id": ...}. Reload the thread and retry |
413 |
Request body over MAX_REQUEST_SIZE (default 10 MB), or upload over MEDIA_MAX_SIZE_MB (default 25) |
415 |
Uploaded content type not allowed |
422 |
Request validation error (malformed body or invalid parameter), a request over the size limits (500 messages, 100 blocks per message, 1,000,000 characters of text), an initial_state, config or resume nested deeper than MAX_NESTING_DEPTH (64 by default) or over the size caps, an Idempotency-Key that is malformed or reused with a different body, an upload with no file part, a resume answer that fails the interrupt’s response_schema, or data the database cannot store, such as a NUL character, a lone surrogate or a number out of range (code INVALID_REQUEST_DATA) |
429 |
Rate limit exceeded. Body has error.code RATE_LIMIT_EXCEEDED; the Retry-After and X-RateLimit-* headers say when to retry. The same status is returned when a user has more than runs.max_concurrent_per_user runs in flight (default 10); that body has code HTTPException and Retry-After: 5. The model provider rate limiting the server also returns 429, with code PROVIDER_RATE_LIMITED and a Retry-After taken from the provider (5 seconds if it sends none) |
499 |
The client closed the request while it waited for a busy thread. The response is never read |
500 |
Unexpected server error. Body has code INTERNAL_SERVER_ERROR; in production the message is generic |
503 |
Checkpointer or storage temporarily unavailable (code SERVICE_UNAVAILABLE for a database or cache driver error that is not a data error), with Retry-After. Readiness answers 503 while the server is shutting down. A rate limiter whose backend is unreachable with fail_open: false also answers 503, with code RATE_LIMIT_UNAVAILABLE and Retry-After: 5 |