Messages and streaming
Send a user message, read the server-sent event stream, and handle tool calls, sources, finish reasons and errors.
You send one user message per turn. The runtime answers with a stream of server-sent events: text as it arrives, tool calls, cited sources, and a final event that says how the turn ended.
Send a turn
POST /v0/sessions/{sessionId}/turns returns 200 OK with Content-Type: text/event-stream.
Browser request. See Authentication.
Prop
Type
A tool spec:
Prop
Type
curl -N -X POST "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/turns" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
-H "x-baseera-user-token: $USER_TOKEN" \
-H "content-type: application/json" \
-d '{
"message": { "text": "Mark this one paid" },
"tools": [
{
"name": "invoices.markPaid",
"description": "Mark an invoice as paid",
"kind": "write",
"inputSchema": {
"type": "object",
"properties": { "invoiceId": { "type": "string" } },
"required": ["invoiceId"]
}
}
],
"context": { "page": "invoice-detail", "entity": { "type": "invoice", "ref": "inv_1042", "title": "Invoice 1042" } }
}'Only one turn runs per session at a time. A second one gets turn_in_progress. A turn whose tool wait expired is closed as tool_timeout when the next turn starts.
Tool names may contain dots. The runtime maps them for providers that do not allow them, and events always use your names.
Refused before the stream
These come back as a JSON error with a status, not as a stream: invalid_request, message_too_large, too_many_tools (also duplicate names), context_too_large, session_not_found, turn_in_progress, agent_not_configured, provider_key_missing, rate_limited, limit_reached. After turn.started, failures arrive as an error event.
Stream format
Each event has an id (a sequence number within the turn, starting at 1), an event name and a JSON data line.
id: 3
event: text.delta
data: {"messageId":"msg_a1","delta":"I'll mark "}
The data object is the event without its type, because the SSE event name carries it.
Event types
| Event | Data | When |
|---|---|---|
turn.started | turnId, messageId | First event of a new turn. messageId is the assistant message being written. |
text.delta | messageId, delta | Text as it arrives. |
tool.call | messageId, callId, name, kind, input, server? | The model wants a tool run. input is complete and validated against inputSchema. |
tool.result | messageId, callId, server: true, status, summary? | A server tool call finished. Only sent for server calls. |
message.sources | messageId, sources | The sources the answer cited. Sent once, just before turn.done, only when the text cites at least one valid source. |
turn.awaiting_tools | turnId, callIds, expiresAt | Last event of this stream. Post results before expiresAt. |
turn.done | turnId, finishReason, usage | Last event of the turn. |
immersive.draft | field, value, reason | The model proposes a value for a field. The user approves or rejects it in the app. |
immersive.ai_check | id, ok, message, fields, sources, severity, blocksFinish | An AI check result. The SDK feeds this shape from the AI checks endpoint; the runtime does not stream it in a turn. |
immersive.notice | checkId | Not emitted yet. |
error | error: { code, message } | Something failed after the stream started. Last event of the stream. |
turn.started
id: 1
event: turn.started
data: {"turnId":"trn_7","messageId":"msg_a1"}tool.call
id: 3
event: tool.call
data: {"messageId":"msg_a1","callId":"call_1","name":"invoices.markPaid","kind":"write","input":{"invoiceId":"inv_1042"}}With "server": true the runtime runs the call itself and your client never runs or approves it. See Server tools.
turn.awaiting_tools
id: 4
event: turn.awaiting_tools
data: {"turnId":"trn_7","callIds":["call_1"],"expiresAt":"2026-11-08T20:35:06.000Z"}Run the tools (asking the user first for draft and write), then post results. See Tools and approvals.
turn.done
id: 6
event: turn.done
data: {"turnId":"trn_7","finishReason":"stop","usage":{"inputTokens":2410,"outputTokens":41}}finishReason is one of:
| Value | Meaning |
|---|---|
stop | The model finished its answer. |
cancelled | You cancelled the turn. |
max_steps_reached | The turn hit the limit of 8 model steps. Tool calls requested on the 8th step are dropped. |
tool_timeout | No tool results arrived within 5 minutes. The session stays usable. |
error
event: error
data: {"error":{"code":"provider_out_of_credit","message":"The Anthropic key has no credit left."}}The codes are listed in Errors.
A full turn with a tool call
id: 1
event: turn.started
data: {"turnId":"trn_7","messageId":"msg_a1"}
id: 2
event: text.delta
data: {"messageId":"msg_a1","delta":"I'll mark invoice 1042 as paid."}
id: 3
event: tool.call
data: {"messageId":"msg_a1","callId":"call_1","name":"invoices.markPaid","kind":"write","input":{"invoiceId":"inv_1042"}}
id: 4
event: turn.awaiting_tools
data: {"turnId":"trn_7","callIds":["call_1"],"expiresAt":"2026-11-08T20:35:06.000Z"}After you post the result, the stream that answers continues the turn:
id: 5
event: text.delta
data: {"messageId":"msg_a1","delta":" Done, it's marked paid."}
id: 6
event: turn.done
data: {"turnId":"trn_7","finishReason":"stop","usage":{"inputTokens":2410,"outputTokens":41}}Server tools
Some tools run in the runtime, not in your app. Today there is one: knowledge.search({ query, topK? }). The runtime adds it whenever the agent has a knowledge base attached. It is never in the tools you send, and the names knowledge.search and knowledge_search are reserved.
A server call arrives as a tool.call with "server": true, followed by a tool.result when the search finishes:
event: tool.result
data: {"messageId":"msg_a1","callId":"call_2","server":true,"status":"done","summary":{"count":4,"sources":["Refund policy"]}}status is done or failed. summary holds counts and source titles, never document text, and is absent when the agent does not store tool data.
- A step whose calls are all server calls continues in the same stream.
turn.awaiting_toolsis not sent. - A step that mixes server and app calls runs the server ones first, then ends with
turn.awaiting_toolslisting only your calls. Answering a server call id returnscall_already_answered.
Sources and citations
With a knowledge base attached, the model cites what it uses as [S1]. Before turn.done, the runtime sends the sources the text cited:
event: message.sources
data: {"messageId":"msg_a1","sources":[{"ref":"S1","title":"Refund policy","section":"Late payments","page":3,"url":"/v0/sessions/ses_01JC9X4M2K8Q/sources/S1?message=msg_a1"}]}A source is { ref, title, section?, page?, url?, aliases? }. Sources are listed in order of first citation, one per document section. The text keeps its [S1] markers. Refs are numbered per turn, so numbers can skip.
url is never a storage URL. It is the runtime path of the link endpoint, and it is present only when the document's owner allows users to open the original. Without url, show the title and section only.
Open a source
GET /v0/sessions/{sessionId}/sources/{ref}?message={messageId}, with the publishable key and user token headers.
curl "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/sources/S1?message=msg_a1" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
-H "x-baseera-user-token: $USER_TOKEN"{ "url": "https://storage.example.com/object/sign/knowledge/...?token=...", "expiresAt": "2026-11-09T10:05:00.000Z" }The URL is signed and valid for 5 minutes. Open it in a new tab with noopener. The runtime checks that the session is the user's, the message is in it, the message cited that ref, and the document still exists, is linkable now, and is platform-wide or belongs to the session's tenant.
Errors: session_not_found (404), source_not_found (404, for every other reason, with no detail), plus the authentication errors. The endpoint is limited to 60 requests a minute per user.
Reconnect to a stream
GET /v0/sessions/{sessionId}/turns/{turnId}/events with the header Last-Event-ID: <seq> (an integer of 0 or more; missing means 0) returns 200 OK with text/event-stream.
curl -N "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/turns/trn_7/events" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
-H "x-baseera-user-token: $USER_TOKEN" \
-H "Last-Event-ID: 3"The runtime stores every event of a turn, so any instance can replay them:
- It replays stored events with a
seqaboveLast-Event-ID, using the storedseqas the SSEid, so ids match the original stream. - If a terminal event (
turn.awaiting_tools,turn.doneorerror) has already gone out, the stream ends there. - If the turn is still running, the runtime checks for new events every 500 ms and sends them until a terminal event goes out or 5 minutes pass. After 5 minutes you may reconnect with the last
idyou saw. - Storing events is best effort. If a write failed, those events are missing from the replay.
- With "Don't store tool data" on,
inputof a storedtool.callevent isnullonce the turn has ended.
Errors: session_not_found (404), turn_not_found (404), invalid_request (400, when Last-Event-ID is not a non-negative integer).
@baseera/core reconnects once per stream. If that attempt fails too, it throws a BaseeraError with code network_error.
Cancel a turn
POST /v0/sessions/{sessionId}/turns/{turnId}/cancel returns 202 Accepted. The open stream ends with turn.done and finishReason: "cancelled".
curl -X POST "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/turns/trn_7/cancel" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
-H "x-baseera-user-token: $USER_TOKEN"Limits
| Limit | Value | Error |
|---|---|---|
| Message text | 8,000 characters | message_too_large |
| Tools per turn | 64 | too_many_tools |
context.data serialized | 4 KB | context_too_large |
| Model steps per turn | 8 | Turn ends with finishReason: "max_steps_reached" |
| Wait for tool results | 5 minutes | Turn ends with finishReason: "tool_timeout" |
See Rate limits and spend for request rates.