The chat stream

Send JSON. The response is always text/event-stream; the server does not read your Accept header, but sending Accept: text/event-stream keeps intermediaries honest. Omit session_id (or send null) on the first turn, the server mints one and hands it back in the first event.

Auth, origin, rate limit, budget and session-ownership checks all run before the stream opens. When one of them rejects the request you get an ordinary JSON response with a non-200 status and no SSE at all — no error event, no [DONE]. A client that goes straight from fetch() to reading the body will find no data: lines and render a blank reply. Check the status first.

The response is a stream of Server-Sent Events. Each frame is a single line of the form data: {json} followed by a blank line. Payloads are never split across lines, so one data: line is always one complete JSON object. Read the type field to decide what to do. The stream always ends with a literal data: [DONE].

Frames carry no event: name and no id: field. Every frame is a default message event and the JSON type is the only discriminator. There are exactly eight event types.

session

Always the first event of the stream, emitted before the agent starts. Carries the session id that was created or reused. Store it and send it back as session_id on the next turn. A server-minted id is an opaque 22-character URL-safe token with no prefix and no structure — do not parse it.

data: {"type":"session","session_id":"kJ2mQ8vX1pR4nT7bW0cLdA"}

text

A chunk of the reply, exactly as the model produced it. Many of these arrive in order. Concatenate the content values to build the full message. Two of these are written by Agentifys rather than the model: the summary line after an approved write, and the cancellation line after a declined one.

data: {"type":"text","content":"Order 1043 shipped "}

tool_start

The agent called a tool. Use it to show live tool status.

data: {"type":"tool_start","id":"toolu_01A9","name":"lookup_order","input":{"order_id":"1043"}}

tool_end

The tool returned. Match it to its tool_start by id.

data: {"type":"tool_end","id":"toolu_01A9","name":"lookup_order","result":{"status":"shipped","eta":"2026-09-02"}}

confirmation_required

A write action is held, waiting for the user to approve it. This event ends the turn — see Resuming a held write for how to release it. Show the display_name and input so the person can see what is about to happen.

data: {"type":"confirmation_required","id":"toolu_01B4","name":"issue_refund","display_name":"Issue refund","input":{"order_id":"1043","amount":"42.00"},"confirm":"__era_confirm__","decline":"__era_decline__"}

stats

Usage for the turn, emitted immediately before the final done. Only on a turn that completes normally: a held write, an approved or declined write, and any failure all skip it.

data: {"type":"stats","input_tokens":812,"output_tokens":140,"tools_used":["lookup_order"],"iterations":2}

error

The turn failed. content is the only field: there is no code, no status, no structured detail. The stream then goes straight to [DONE] with no stats and no done, so any text already streamed is all the reply you get.

data: {"type":"error","content":"PROJECT_NO_API_KEY"}

There are four possible contents:

done

The turn completed. Carries a trace_id: 8 hex characters, which you pass to /v1/feedback to rate this reply. Not emitted on a failed turn, so do not treat it as the end-of-stream signal.

data: {"type":"done","trace_id":"9f3a1c7d"}

[DONE]

The final line, on every outcome. Not JSON. When you read it, stop reading and close the stream.

data: [DONE]

Only two events are guaranteed: session first and [DONE] last. Everything between depends on how the turn ends. An asterisk means zero or more.

normal turn        session -> text* -> (tool_start -> tool_end)* -> text* -> stats -> done -> [DONE]
held write         session -> text* -> confirmation_required -> done -> [DONE]
resume (approve)   session -> tool_start -> tool_end -> text -> done -> [DONE]
resume (decline)   session -> text -> done -> [DONE]
failed turn        session -> text* -> error -> [DONE]

Two consequences worth building for. done is absent on a failed turn, so close on [DONE], not on done. And stats only appears on a turn that runs to completion, so a usage counter wired to it will undercount held writes and failures.

A tool marked requires confirmation is never executed straight from the model. SSE is one-way and cannot block mid-stream for a click, so Agentifys stores the pending call against the session, emits confirmation_required, and ends the turn. Nothing further happens until you send another message on that session. A custom UI that renders the event but never sends the follow-up leaves the write held forever.

The resume is an ordinary POST /v1/chat whose message is the token from the event, on the same session_id.

POST /v1/chat
Authorization: Bearer era_your_project_key
Content-Type: application/json

{
  "message": "__era_confirm__",
  "user_context": { "id": "u_42", "name": "Sara" },
  "session_id": "kJ2mQ8vX1pR4nT7bW0cLdA"
}

The two tokens are __era_confirm__ and __era_decline__, and every confirmation_required event ships them in its confirm and decline fields. Read them off the event.

const { text, held } = await send("Refund order 1043")

if (held) {
  // held.display_name and held.input are what the person approves.
  // The event carries the exact tokens; do not hardcode them.
  const approved = await askTheUser(held.display_name, held.input)

  // Same session_id, next turn. send() above already keeps it.
  await send(approved ? held.confirm : held.decline)
}

What each resume produces:

Putting the endpoint behind your own server is the normal way to keep the project key off the browser. A proxy that treats the response like an ordinary JSON body will break streaming in ways that look like a slow or empty agent, so a few things have to be right.

Agentifys responds with Content-Type: text/event-stream, Cache-Control: no-cache and X-Accel-Buffering: no. Forward all three to the client unchanged.

An agent can end a reply with a fenced code block tagged choices holding a JSON array of short strings. The system prompt asks for 2 to 6 of them; the renderer accepts 1 to 8 non-empty strings and falls back to plain text for anything else. It arrives inside the text events like any other markdown, so a custom UI has to strip the block out of the transcript before rendering, then draw the buttons itself. Clicking a button sends that option string as the next message.

A second fenced block, era-ui, carries in-page pointing instructions for the embedded widget. If you render your own transcript and do not handle it, strip it anyway, or a JSON blob will show up at the end of the reply. Both blocks are always the last thing in the message.