Skip to main content
An event is a record of one thing that happened to a document: it was queued, a block of text was written, a page was rendered, it finished. Events are not the document; they tell you how it is going. You use them in two places:
  • GET /documents/{id}/events: a live stream (SSE) for logs and progress bars.
  • Webhooks: a signed POST to 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 your content, 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 with sources:
Progress events arrive in between. Behavior to be aware of:
  • 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.resolved and no content.*. 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.started arrives again with a higher attempt.
To render a document on the client, set up the styles from 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:
The SDKs read the stream for you:
Behavior to be aware of:
  • 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=13 in the SDKs). You get the events after 13, then the live ones. The document keeps being made while you’re disconnected.
  • Heartbeat: a : heartbeat comment 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, /events answers 410 events_expired. The document itself is still available with GET /documents/{id}.
  • Once the retention ends, /events answers 410 content_deleted.

Webhooks

Get the final events on your server, signed.

Modes

Wait for the document, or follow it in the background.