Skip to Content
Baseera Docs

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

EventDataWhen
turn.startedturnId, messageIdFirst event of a new turn. messageId is the assistant message being written.
text.deltamessageId, deltaText as it arrives.
tool.callmessageId, callId, name, kind, input, server?The model wants a tool run. input is complete and validated against inputSchema.
tool.resultmessageId, callId, server: true, status, summary?A server tool call finished. Only sent for server calls.
message.sourcesmessageId, sourcesThe sources the answer cited. Sent once, just before turn.done, only when the text cites at least one valid source.
turn.awaiting_toolsturnId, callIds, expiresAtLast event of this stream. Post results before expiresAt.
turn.doneturnId, finishReason, usageLast event of the turn.
immersive.draftfield, value, reasonThe model proposes a value for a field. The user approves or rejects it in the app.
immersive.ai_checkid, ok, message, fields, sources, severity, blocksFinishAn AI check result. The SDK feeds this shape from the AI checks endpoint; the runtime does not stream it in a turn.
immersive.noticecheckIdNot emitted yet.
errorerror: { 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:

ValueMeaning
stopThe model finished its answer.
cancelledYou cancelled the turn.
max_steps_reachedThe turn hit the limit of 8 model steps. Tool calls requested on the 8th step are dropped.
tool_timeoutNo 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_tools is not sent.
  • A step that mixes server and app calls runs the server ones first, then ends with turn.awaiting_tools listing only your calls. Answering a server call id returns call_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 seq above Last-Event-ID, using the stored seq as the SSE id, so ids match the original stream.
  • If a terminal event (turn.awaiting_tools, turn.done or error) 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 id you saw.
  • Storing events is best effort. If a write failed, those events are missing from the replay.
  • With "Don't store tool data" on, input of a stored tool.call event is null once 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

LimitValueError
Message text8,000 charactersmessage_too_large
Tools per turn64too_many_tools
context.data serialized4 KBcontext_too_large
Model steps per turn8Turn ends with finishReason: "max_steps_reached"
Wait for tool results5 minutesTurn ends with finishReason: "tool_timeout"

See Rate limits and spend for request rates.

Next steps

On this page