Streaming
GET /threads/{threadId}/stream and GET /subagents/{subagentId}/stream hold a connection open and push what GET /threads/{threadId}/messages would page: the same Message entries, in the same order, as their rows commit. On top of that they carry the turn in progress, so you can show the agent's reply as it is written and the tools it is calling, without polling.
curl -N "https://api.capy.ai/api/v1/threads/$THREAD_ID/stream" \
-H "Authorization: Bearer $CAPY_API_KEY" \
-H "Accept: text/event-stream"The response is text/event-stream. Each frame is an event: name and one JSON data: line; transcript frames also carry an id: line, the cursor you resume from. A retry: 2000 line follows the first frame, the delay to wait before reconnecting after a dropped connection.
event: status
data: {"threadId":"jam_01...","status":"working"}
retry: 2000
event: run
data: {"phase":"start"}
event: turn
data: {"phase":"start"}
event: tool_call
data: {"callId":"toolu_01A...","name":"bash","text":"Running the test suite"}
event: turn
data: {"phase":"end","outcome":"settled"}
id: 01J...
event: transcript
data: {"id":"toolu_01A...","source":"tool","tool":"bash","text":"Running the test suite","createdAt":"..."}
event: turn
data: {"phase":"start"}
event: assistant
data: {"callId":"toolu_01B...","text":"Tests pass. "}
event: assistant
data: {"callId":"toolu_01B...","text":"PR is up."}
event: turn
data: {"phase":"end","outcome":"settled"}
id: 01J...
event: transcript
data: {"id":"01J...","source":"assistant","callId":"toolu_01B...","text":"Tests pass. PR is up.","model":"...","createdAt":"..."}
event: run
data: {"phase":"end"}
event: status
data: {"threadId":"jam_01...","status":"idle"}The browser EventSource cannot send an Authorization header, so read the stream with fetch (or any HTTP client) and parse the frames yourself. Ignore event names you do not know: the vocabulary grows over time and a newer server may send names this page does not list.
Events
| Event | Data | When |
|---|---|---|
status | Thread: { threadId, status } with the thread's status values. Subagent: { subagentId, subagentPath, status, archived }, the subagent's fields. | First frame on every connection, then on every change. |
transcript | One Message entry, identical to the transcript endpoints' items. | When a row commits. Carries id:. |
run | { phase: "start" | "end" } | A run is one wake of the agent: every model turn and tool execution until it comes to rest. |
turn | { phase: "start" } or { phase: "end", outcome: "settled" | "aborted" | "dropped" } | A turn is one model generation. |
assistant | { callId, text } | A fragment of the agent's reply, in order within callId, while it is being written. |
tool_call | { callId, name, text } | A tool call as soon as its input has parsed; text is the same one-line summary the transcript's tool entry carries. |
subagent | { subagentId, subagentPath, status, archived } | Thread streams opened with frames=subagent: a subagent under the thread was created, changed status, or was stopped or resumed. |
task | { taskId, taskPath, status, archived } | Thread streams opened without frames=subagent: the same subagent change, under the field names the stream first shipped with. |
heartbeat | {} | Every 15 seconds while nothing else was sent. |
error | { code, message } | The server closes the stream after it. code is unauthorized, forbidden, or internal. |
done | {} | The server closes the stream after it: the thread was archived or deleted, the subagent reached done, or until=run was satisfied. |
Live frames show what the transcript will contain, before it commits. Two rules connect them:
- A
transcriptframe withsource: "assistant"carries thecallIdof the delivery call it came from. When it arrives, replace everyassistantfragment you accumulated under thatcallIdwith the entry's text. - A
transcriptframe withsource: "tool"has the sameidas thetool_callframe'scallId. Replace the live frame with the entry.
Fragments whose callId never settles into a transcript frame belong to a turn that was interrupted or a reply whose delivery failed; discard them at the next run end. A turn end with outcome dropped means the server discarded live frames of that turn because you were reading too slowly or the turn was too large to replay; the transcript frames still arrive in full. Treat live frames as a preview and transcript frames as the record.
The stream carries nothing the transcript hides: tool activity is the rendered summary, never arguments or results, and the only text that streams is the reply being delivered to you, never the model's internal reasoning.
Resuming
Store the last id: you read. On reconnect, send it as the Last-Event-ID header (or the after query parameter, when you cannot set headers) and the stream replays every transcript entry after that cursor, then the turn in progress, then continues live. Cursors are the transcript's event ids and never expire.
curl -N "https://api.capy.ai/api/v1/threads/$THREAD_ID/stream" \
-H "Authorization: Bearer $CAPY_API_KEY" \
-H "Last-Event-ID: $LAST_ID"A value that is not a valid cursor answers 400 capy/InvalidRequest before the stream starts.
Waiting for one reply
Pass until=run to close the stream once the run in progress ends. You get every frame of the run, the transcript entries it committed, then done. When the thread is not working and has nothing queued, done arrives right away.
curl -X POST "https://api.capy.ai/api/v1/threads/$THREAD_ID/message" \
-H "Authorization: Bearer $CAPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Add a changelog entry for this release."}'
curl -N "https://api.capy.ai/api/v1/threads/$THREAD_ID/stream?until=run" \
-H "Authorization: Bearer $CAPY_API_KEY"This replaces the poll-until-idle loop: send a message, open the stream with until=run, and read until it closes. The reply is the last transcript entry with source: "assistant". Without a cursor the stream first replays the whole transcript; pass the last id: you read as Last-Event-ID or after to skip it.
Subagent streams
GET /subagents/{subagentId}/stream carries one subagent's own turns with the same frames. Its status frame has the subagent shape, and it closes with done when the subagent's status reaches done. A thread stream does not carry its subagents' tokens, only their lifecycle; open a subagent's stream when you want to follow its work.
A thread stream reports subagent lifecycle as task frames by default. Pass frames=subagent to receive subagent frames instead:
curl -N "https://api.capy.ai/api/v1/threads/$THREAD_ID/stream?frames=subagent" \
-H "Authorization: Bearer $CAPY_API_KEY"frames=task selects the default explicitly. Any value other than task or subagent answers 400 capy/InvalidRequest before the stream starts.
GET /tasks/{taskId}/stream, the original name of the subagent stream, still works. It carries the same frames, its status frame keeps the { taskId, taskPath, status, archived } shape, and it answers 404 capy/TaskNotFound where the subagent stream answers capy/SubagentNotFound.
Limits
- The stream authenticates like every other request and answers
404 capy/ThreadNotFoundorcapy/SubagentNotFoundwhere the JSON reads do. Every error before the first byte is an ordinary JSON error; after that, failures arrive as anerrorframe. - Your API key is re-verified every 15 seconds. A key revoked, expired, or disabled while a stream is open closes it with
errorcodeunauthorizedwithin that interval. - The same check confirms the key can still reach the thread's project. A service key that loses access to that project closes the stream with
errorcodeforbiddenwithin that interval. - A server that can't serve streams answers
503 capy/StreamUnavailablebefore the stream starts. Wait and retry. - Each API server holds a fixed number of open streams in total and per key principal. Above either limit, a new connection answers
429 capy/RateLimitedwithretryAfterSecondsand a matchingretry-afterheader. Wait that many seconds and retry. - A connection can be cut without a closing frame when a server restarts. Treat any close without
doneorerroras a resume: waitretrymilliseconds and reconnect withLast-Event-ID. - The heartbeat keeps idle connections alive through proxies. If your client has its own idle timeout, set it above 15 seconds.