Thread endpoints

In shortReference for the 10xGraph REST endpoints that read and write thread state and messages, with request fields, responses, and auth requirements.

  • 9 min read
  • 16 sections
  • Updated
  • v1.0.0
  • Markdown

The thread endpoints read and manage what the checkpointer stores for a conversation: the thread record, its saved state and its messages. Every route lives under /v1/threads and is addressed by thread_id. Each route needs a threads permission when auth is configured.

Route summary

The server exposes ten thread routes. Reads need threads:read, writes need threads:write, and deletes need threads:delete. There is no route to import messages.

Method Path Permission
GET /v1/threads threads:read
GET /v1/threads/{thread_id} threads:read
DELETE /v1/threads/{thread_id} threads:delete
GET /v1/threads/{thread_id}/state threads:read
PUT /v1/threads/{thread_id}/state threads:write
DELETE /v1/threads/{thread_id}/state threads:delete
GET /v1/threads/{thread_id}/messages threads:read
GET /v1/threads/{thread_id}/messages/{message_id} threads:read
PUT /v1/threads/{thread_id}/messages/{message_id} threads:write
DELETE /v1/threads/{thread_id}/messages/{message_id} threads:delete

There is no create-thread endpoint. A thread is created implicitly when POST /v1/graph/invoke or POST /v1/graph/stream omits thread_id and the server generates one. With runs.thread_ids set to client, the first request that names an unused id creates it instead. See Graph endpoints.

Response envelope and shared rules

Every successful response is a JSON object with a data field holding the result and a metadata object with request_id, timestamp and message. The examples below show only the data value. If no checkpointer is configured, the routes return 503 with Checkpointer is not configured. See REST API conventions for the full envelope and error format.

Rule Behavior
thread_id type String or integer. An empty or whitespace-only string, or an integer below 1, returns 422.
limit Default 100, clamped to a maximum of 1000. A value of 0 or less returns 422.
offset Must be >= 0, otherwise 422.
config in a request body Client keys are merged into the checkpointer config. The path thread_id always wins, and the server-owned keys user, user_id, remote_tools and any key starting with _ are dropped.

The curl examples in this page assume a local server on port 8000 and a token in $TOKEN. Omit the Authorization header if auth is not configured.

List threads

GET /v1/threads returns the threads stored in the checkpointer. The listing is scoped to the calling user by the service layer.

Query parameter Type Default Description
search string none Free-text filter over thread records
offset integer none Number of threads to skip. A negative value returns 422
limit integer 100 Page size. A value above 1000 is lowered to 1000; zero or a negative value returns 422
filters string (JSON object) none Column conditions, for example {"plan": "pro", "created_at": {"gte": "2026-01-01T00:00:00+00:00"}}. Filterable: thread_name, created_at, updated_at and the checkpointer’s extra columns. Tenant columns and user_id are refused. Needs PgCheckpointer. Invalid JSON, a column or operator that is not allowed, or a checkpointer without filterable columns returns 422. At most 8192 characters. See Filters
Terminal
# List the first 20 threads whose records match "weather"
curl "http://localhost:8000/v1/threads?search=weather&limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Only threads whose "plan" extra column is "pro"
curl -G "http://localhost:8000/v1/threads" \
  --data-urlencode 'filters={"plan": "pro"}' \
  -H "Authorization: Bearer $TOKEN"

Each item is a thread record with thread_id, thread_name, user_id, metadata, updated_at and run_id (the full field set of ThreadInfo; unset fields are null).

JSON
{
  "threads": [
    {"thread_id": "t1", "thread_name": "Weather in Paris", "user_id": "user-123", "metadata": null, "updated_at": "2026-04-01T10:00:00", "run_id": null}
  ]
}

Get a thread

GET /v1/threads/{thread_id} returns the record for one thread: its metadata, not its messages or state. The record is nested under thread_data.thread, and thread is null when the checkpointer has no record.

Terminal
# Fetch the record for thread t1
curl http://localhost:8000/v1/threads/t1 -H "Authorization: Bearer $TOKEN"
JSON
{
  "thread_data": {
    "thread": {"thread_id": "t1", "thread_name": "Weather in Paris", "user_id": "user-123", "metadata": null, "updated_at": "2026-04-01T10:00:00", "run_id": null}
  }
}

Delete a thread

DELETE /v1/threads/{thread_id} removes a thread and its checkpointed data. The request body is required: send {} or {"config": {}}.

Terminal
# Delete thread t1 (the body is required, even when empty)
curl -X DELETE http://localhost:8000/v1/threads/t1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {}}'
JSON
{"success": true, "message": "Thread deleted successfully", "data": null}

If file or trace cleanup fails after the thread is deleted, the answer is success: false with the message Thread deleted, but cleanup did not finish: <steps> and data like this. The thread itself is gone. A delete also releases the files linked to that thread by their own metadata, even when no message references them (local and memory media stores; the cloud store cannot list its files, so it is skipped). A file left with no thread is deleted only with media.delete_with_thread on, which is the default.

JSON
{"success": false, "message": "Thread deleted, but cleanup did not finish: traces", "data": {"deleted": true, "cleanup_failed": ["traces"], "result": {}}}

cleanup_failed lists the steps that failed. Check success before you treat the delete as fully clean. On success, the inner data is whatever the checkpointer returns from its clean-up. The server also deletes the thread’s telemetry traces when a telemetry store is bound.

Thread and message 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. Other ids in the path or body get 422 VALIDATION_ERROR. See Conventions.

Writes while a run is active

These routes answer 409 (code HTTPException, message thread is busy, Retry-After: 5) at once while a run holds the thread, instead of waiting: PUT /v1/threads/{thread_id}/state, DELETE /v1/threads/{thread_id}/state, DELETE /v1/threads/{thread_id}/messages/{message_id}, DELETE /v1/threads/{thread_id} and POST /v1/graph/fix. A write that raced a run would be overwritten by it, or would bring a deleted thread back. Retry after the run ends, or stop it with POST /v1/graph/stop.

Get thread state

GET /v1/threads/{thread_id}/state returns the saved state for a thread. If the checkpointer has no persisted state, the server falls back to the state cache.

Terminal
# Read the saved state of thread t1
curl http://localhost:8000/v1/threads/t1/state -H "Authorization: Bearer $TOKEN"
JSON
{
  "state": {
    "context": [
      {"role": "user", "content": [{"type": "text", "text": "Hello"}]},
      {"role": "assistant", "content": [{"type": "text", "text": "Hi there!"}]}
    ]
  }
}

The exact fields depend on your AgentState subclass. state is null when nothing is stored. Messages in context carry no raw field, and execution_meta.internal_data holds only error when a run failed. With MODE=production that error is a generic message with its error code, as in stream error chunks, not the exception text. The rest of internal_data stays on the server.

Update thread state

PUT /v1/threads/{thread_id}/state merges the fields you send into the existing state, writes the result to the checkpointer and the cache, and returns the merged state.

Field Type Required Description
state object yes State fields to merge into the current state
config object no Extra keys merged into the checkpointer config

The merge rules are fixed. context is appended to the existing list, not replaced. Nested dictionaries are deep-merged, other values overwrite, and null values are ignored. The server refuses some input with 422:

  • The built-in fields context_summary and execution_meta can never be set by a client.
  • Messages in context must be user messages. A message with role assistant or system returns 422. A tool message is accepted only as tool_result blocks that answer a pending client tool call.
  • Messages that carry a tool call return 422, because only the model may request tools.
  • Any message_id you send in context is ignored. The server generates the ids.
  • A value that does not match the type of its state field returns 422 and names the field. This includes context, which must be a list of messages.

Custom state fields are denied unless the operator lists them in runs.state_keys in 10xgraph.json; only listed keys are accepted. context is always allowed.

Terminal
# Add a custom field to the state before the first invoke
curl -X PUT http://localhost:8000/v1/threads/t1/state \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": {"user_id": "user-456"}, "config": {}}'

The response data has the same shape as the get-state response: {"state": {...}} with the merged state. Use this endpoint to seed custom fields before the first invoke call or to repair inconsistent state. A custom field must exist on your state class to survive validation.

Clear thread state

DELETE /v1/threads/{thread_id}/state clears the saved state for a thread, so the next invoke call with this thread_id starts fresh. It takes no body.

Terminal
# Clear the saved state of thread t1
curl -X DELETE http://localhost:8000/v1/threads/t1/state -H "Authorization: Bearer $TOKEN"
JSON
{"success": true, "message": "State cleared successfully", "data": null}

Here too, the inner data is the checkpointer’s return value.

List messages

GET /v1/threads/{thread_id}/messages returns the conversation messages stored for a thread.

Query parameter Type Default Description
search string none Free-text filter over message content
offset integer none Number of messages to skip. A negative value returns 422
limit integer 100 Page size. A value above 1000 is lowered to 1000; zero or a negative value returns 422
Terminal
# Read up to 50 messages from thread t1
curl "http://localhost:8000/v1/threads/t1/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN"
JSON
{
  "messages": [
    {"message_id": "m1", "role": "user", "content": [{"type": "text", "text": "Hello"}]},
    {"message_id": "m2", "role": "assistant", "content": [{"type": "text", "text": "Hi there!"}]}
  ]
}

Each item is a Message object. Fields such as timestamp, metadata and usages are also included; they are omitted above for brevity.

Get a message

GET /v1/threads/{thread_id}/messages/{message_id} returns a single Message object as data. An empty or whitespace-only message_id returns 422, and a message_id the thread does not have returns 404. The provider’s raw response (raw) is never included.

Terminal
# Fetch message m1 from thread t1
curl http://localhost:8000/v1/threads/t1/messages/m1 -H "Authorization: Bearer $TOKEN"

Set message feedback

PUT /v1/threads/{thread_id}/messages/{message_id} stores feedback on a message, for example a thumbs up or down with a comment. It writes to message.metadata["feedback"] and replaces any earlier feedback. Nothing else on the message can change.

Field Type Required Description
feedback object yes Any JSON object. At most 8 KB serialized and 10 levels deep, otherwise 422.
Terminal
# Record a thumbs-down with a comment on message m2
curl -X PUT http://localhost:8000/v1/threads/t1/messages/m2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feedback": {"rating": "down", "comment": "Wrong city"}}'

The response data is the updated Message, the same shape as Get a message. The route returns 404 when the thread has no such message, and 501 when the checkpointer lacks aupdate_message_metadata (added in 10xgraph 1.0; the message is “This checkpointer does not support message feedback”).

Delete a message

DELETE /v1/threads/{thread_id}/messages/{message_id} removes one message. The body is required and takes the same config object as the other write routes. A message_id the thread does not have returns 404.

Terminal
# Delete message m1 from thread t1
curl -X DELETE http://localhost:8000/v1/threads/t1/messages/m1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {}}'
JSON
{"success": true, "message": "Message deleted successfully", "data": null}

Authentication and ownership

When auth is configured, every thread route requires a bearer token and the permission shown in the route summary. A failed login returns 401. A missing permission returns 403. A thread owned by someone else, or one that does not exist, returns 404. When auth is not configured, these checks are skipped entirely.

Ownership is enforced in storage: every query is filtered by the caller’s reach. The default reach is own, so a request for another user’s thread answers 404 for every action, before it reaches the graph. A role with reach tenant or all can also read, list and delete threads outside its own, but state and message writes (PUT) and runs always stay on the caller’s own threads. A thread_id that does not exist yet is refused with 404, the same answer as for another user’s thread, unless runs.thread_ids is client. A new thread is started by omitting the id. The checkpointer write routes follow the same rule. See runs.thread_ids and Authentication and authorization.

See Authentication for the backends and how to write your own.

Frequently asked questions

How do I create a thread over the REST API?
There is no create-thread endpoint. A thread comes into existence when you call the invoke or stream endpoint without a thread_id and the server generates one. With `runs.thread_ids` set to `client`, it also comes into existence the first time a request uses an id you picked.
Why do I get 404 on a thread I know exists?
With auth on, a thread can only be reached by the user who owns it (or by a role whose reach is wider, for reads and deletes). To anyone else it does not exist, so the answer is 404, never 403. A missing permission returns 403.
Is the limit parameter capped?
Yes. The list endpoints default to 100 items and clamp any larger limit to 1000. A limit of 0 or less returns 422.
Last updated for v1.0.0Edit this page on GitHubReport an issue