Threads
Agents
Threads
Read, update, delete, stream, and publish thread events
GET
Threads
Threads are the canonical cloud conversation surface. Durable events are stored as JSONL in workspace storage and projected into
Pass exactly one of
Transient frame types:
Transient frames require
agent_threads and thread_rollouts for fast listing; transient token/reasoning deltas are live-only WebSocket frames. Reach for threads when you want conversation history, multi-client live updates, compaction, or local-device runs that publish back into cloud history.
Thread Management
number
default:"50"
List endpoints cap
limit at 100 for thread lists and 500 for event reads.string
Cursor returned in
meta.nextCursor.boolean
Include archived threads when listing.
string
Use
include=all_rollouts on snapshot or event reads when you need non-active rollout history.cURL
cURL
Live WebSocket
Subscribe to live thread frames:api_key or token. The first frame is a snapshot for the owner, or a metadata-only snapshot for admin broader-view access.
Common live frames:
Publish Thread Events
Public clients that execute local runs, such as the desktop sidecar, publish throughPOST /v1/thread-events. This route requires user or API-key auth and rejects internal service headers.
Durable frame types:
threadId, runId, rolloutId, and a positive sequenceNumber. They fan out to WebSocket subscribers but do not write JSONL or bump durable thread timestamps.
cURL
Thread Busy
Only one active run may write a thread at a time. Starting another run on a busy thread returns409 THREAD_BUSY.