Skip to main content
A thread is one conversation (or one run) owned by an agent. Inside it, a turn is one admitted input plus all the work it sets off, and an event is one permanent entry in the log. Threads never cross agents, and an agent’s threads can’t read each other. A message is an ordered content array of text and image blocks rather than a plain string. That’s what POST /v1/agents/{agentId}/threads takes to create a thread and admit its first turn. Two optional fields can ride along: maxCost caps what the whole thread may spend, and model pins the turn to one exact catalog ID. To send more input, POST /v1/threads/{threadId}/messages. The mode field says what to do about work already running: queue waits its turn, steer redirects the turn in flight, and interrupt stops it and goes now. POST .../cancel drops active and queued work but keeps the history. There are two ways to watch progress. The event log is the source of truth, complete and replayable and paginated by cursor. The SSE streams are best-effort and meant for keeping a UI live. When correctness matters, reconnect and read the log. An agent can also kick off side work with thread.create and wait on it with thread.wait. Each sibling thread gets a fresh transcript and context window under the same agent.
Belongs to one agent · Has many turns → events · Status is running | awaiting | idle | failed | cancelled

​
Rules

  • Each admitted turn freezes its configuration. See How it fits together.
  • Sibling threads share memory and credentials, not transcripts.

​
API

  • Event types, statuses, modes, block limits: Thread events.
  • GET /v1/threads?state=waiting for everything parked on a human.