GET /documents/{id}/events: a live stream (SSE) for logs and progress bars.- Webhooks: a signed
POSTto your server for the final events only.
Event shape
content.* events carry document content, and so do agent.delivered (a summary) and design.chosen (a file name).
Webhooks never carry content.
Types
Lifecycle
⏹ marks a final event: nothing else arrives after it.
error.code values are listed in
when a document fails.
Content
These arrive while a document is created from yourcontent, or from a prompt with sources or web results, so you
can show its text before the file exists. A document created from a prompt alone doesn’t send them: the agent writes
the text straight into the file, and you follow it with the agent’s progress events.
Files
output.available has no URL: get it with GET /documents/{id}/outputs or from the finished document.
Progress
While Doconda decides and makes the file, these also arrive:request.understood, quality.chosen, route.chosen,
design.chosen, artifact.checked, agent.started, agent.step, agent.checked and agent.delivered. Show their
display if they have one, or ignore them. Their data may change.
Typical order
Create from a prompt withsources:
- Create from
content: the same order, but the blocks arrive almost all at once. - Create from a prompt alone: no
content.*. You get the agent’s progress, then the render, pages and final event. - Edit: no
style.resolvedand nocontent.*. You get the agent’s progress, then the render, pages and final event. What changed is in the report (changes). - Retries: if a document is retried after a temporary failure,
document.startedarrives again with a higherattempt.
style.resolved, build an approximate view from
content.*, then replace it with the real pages from preview.page_ready.
Follow a document live
GET /documents/{id}/events is a Server-Sent Events (SSE) stream. Each event is one frame:
- Replay: the stream first sends every stored event, then continues live. A finished document’s stream sends its events and closes.
- Reconnect: send the header
Last-Event-ID: 13, or?after=13(after=13in the SDKs). You get the events after 13, then the live ones. The document keeps being made while you’re disconnected. - Heartbeat: a
: heartbeatcomment every 15 s keeps proxies from closing the connection. - End: the server closes the connection after the final event.
How long events are kept
Events are kept for 7 days after the document finishes, or less if its retention is shorter.- After 7 days,
/eventsanswers410 events_expired. The document itself is still available withGET /documents/{id}. - Once the retention ends,
/eventsanswers410 content_deleted.
Related
Webhooks
Get the final events on your server, signed.
Modes
Wait for the document, or follow it in the background.