Streaming

Stream tokens as they generate using Server-Sent Events. Same request shape as /v1/chat — different endpoint, different response format.

Endpoint

http

POST https://api.sentientone.ai/v1/chat/stream

Available on Pro and Enterprise. On Starter the endpoint returns 403 with plan_upgrade_required.

Request

Identical to POST /v1/chat — same headers, same body fields. The platform decides which endpoint to read based on the URL.

bash

curl -N -X POST https://api.sentientone.ai/v1/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk-so-YOUR_KEY" \
  -H "X-Agent-Id: YOUR_AGENT_ID" \
  -d '{ "message": "Stream me a haiku about agents." }'

Response — Server-Sent Events

The response is Content-Type: text/event-stream. Read line-by-line; each event is a JSON payload prefixed with data: .

text

data: {"type":"start","conversation_id":"conv-..."}

data: {"type":"delta","content":"Tokens "}

data: {"type":"delta","content":"arriving "}

data: {"type":"delta","content":"one at a time."}

data: {"type":"tool_call","name":"get_order","input":{"order_id":"ORD-1234"}}

data: {"type":"done","message":{"id":"msg-...","content":"Tokens arriving one at a time.","token_count":18}}

Event types

startFirst event. Carries the conversation_id — store it now so a network drop later still lets you reconnect.
deltaIncremental token chunk. content is the new substring to append to the in-progress reply.
tool_callEmitted when the agent invokes an MCP tool. Carries the tool name and its input. The output arrives in the final done event.
doneFinal event. Carries the full saved message with its id, token count, and any tool call outputs.
errorEmitted when something goes wrong mid-stream. Carries an error code matching the codes in Error Codes.

JavaScript example

javascript

const res = await fetch("https://api.sentientone.ai/v1/chat/stream", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": process.env.SENTIENTONE_KEY,
    "X-Agent-Id": process.env.SENTIENTONE_AGENT,
  },
  body: JSON.stringify({ message: "Stream me a haiku." }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  for (const line of buffer.split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const event = JSON.parse(line.slice(6));
    if (event.type === "delta") process.stdout.write(event.content);
  }
  buffer = buffer.endsWith("\n") ? "" : buffer.split("\n").pop() ?? "";
}

Reconnect strategy

SSE streams die when the client loses the network. Store the conversation_id from the start event so you can issue a new request that picks up where the stream left off.