Skip to main content
GET
Threads
Threads are the canonical cloud conversation surface. Durable events are stored as JSONL in workspace storage and projected into 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:
Pass exactly one of 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 through POST /v1/thread-events. This route requires user or API-key auth and rejects internal service headers. Durable frame types:
Transient frame types:
Transient frames require 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 returns 409 THREAD_BUSY.