Chat streaming

The chat stream runs one turn of the in-app agent, the ask_assistant capability, and sends it back as Server-Sent Events (SSE). The Oxagen app's assistant reads this same route.

To get the whole reply as one JSON response instead, call POST /v1/{orgSlug}/{workspaceSlug}/assistant/ask. It takes content, conversationId, turnId, attachments, and goal, and returns the same object the stream's done event carries. It refuses the model override fields.

EndpointCopy Anchor Link

POST https://api.oxagen.sh/v1/{orgSlug}/{workspaceSlug}/chat/stream

Use the org and workspace your API key belongs to. A path that names another org or workspace gets 403 with error.reason key_scope_mismatch.

The turn acts for a person: the signed-in user, or the person who created the API key. The caller needs a role ask_assistant grants: organization Owner, or workspace Admin or Member. A workspace API key acts as a Member, so it can ask.

RequestCopy Anchor Link

POST /v1/acme-corp/engineering/chat/stream
Authorization: Bearer ox_…
Content-Type: application/json

{
  "content": "Summarize the last 10 agent runs and identify any failures.",
  "conversationId": "cnv_…"
}

Refusals before the stream opensCopy Anchor Link

The route checks the request, the caller's role, and billing before it opens the stream. A refusal at that point is not a stream. It is a JSON error with the same status and body as POST /assistant/ask:

ResponseCopy Anchor Link

The response has Content-Type: text/event-stream. Each event is a JSON object on a data: line, followed by a blank line. The stream starts with run and sends usage last, just before done.

data: {"type":"run","runId":"tse_…"}

data: {"type":"step-start","stepIndex":0}

data: {"type":"tool-call-start","toolCallId":"call_1","capability":"list_runs","inputPreview":{"limit":10},"riskLevel":"low"}

data: {"type":"tool-call-end","toolCallId":"call_1","status":"completed","output":{"runs":[...]},"durationMs":142}

data: {"type":"text","text":"Here are the last 10 agent runs:"}

data: {"type":"step-finish","stepIndex":0}

data: {"type":"usage","usage":{"promptTokens":1240,"completionTokens":312,"totalTokens":1552}}

event: done
data: {"conversationId":"…","conversationPublicId":"cnv_…","userMessageId":"…","assistantMessageId":"…","runId":"tse_…","reply":"Here are the last 10 agent runs: …","parkedCards":[],"toolCalls":[…],"stopped":false}

Event typesCopy Anchor Link

End of the streamCopy Anchor Link

The stream always ends with a named SSE event, done:

• The turn finished. The data: line is the ask_assistant output as JSON: conversationId (UUID), conversationPublicId (cnv_…), userMessageId, assistantMessageId, runId, reply (the whole reply), parkedCards, toolCalls, and stopped.
• The turn failed. An error event comes first, and the data: line of done is the text [DONE].

event: done
data: [DONE]

Each entry in toolCalls gives toolCallId, toolName, outcome (completed, failed, denied, cancelled, or parked), durationMs, and approvalId (set only on a parked call).

ApprovalsCopy Anchor Link

A tool call that needs a person's approval does not run, and the turn does not wait for it. The stream sends approval-required, the turn goes on, and the done event lists every parked call in parkedCards. Each card gives approvalId (apr_…), capability, and expiresAt.

Answer each one before its expiresAt:

POST /v1/{orgSlug}/{workspaceSlug}/agent/approvals/resolve
Authorization: Bearer ox_…
Content-Type: application/json

{
  "approvalId": "apr_…",
  "decision": "approved"
}

• decision is "approved" or "denied". An optional note string records why.
• approvalId takes the apr_ public ID or the UUID that the approval-required event carried.
• Only the person who asked the turn can answer its approvals. For a turn asked with an API key, that person is the key's creator.
• An approval that expired, was already answered, or belongs to someone else gets 409 with error.reason approval_expired.

When you approve, Oxagen runs the parked call as a new run. The response's execution field says what happened: status (succeeded, dispatched, failed, indeterminate, queued, denied, or expired), the runId of the new run, and a reason when the call failed.

QuestionsCopy Anchor Link

The agent can stop and ask you a question when it cannot go on without your choice. The stream sends question with the question's id, its text, and the options the agent offered, which may be empty. The turn waits for your answer.

Answer it with the id:

POST /v1/{orgSlug}/{workspaceSlug}/assistant/question/answer
Authorization: Bearer ox_…
Content-Type: application/json

{
  "questionId": "…",
  "answer": "Staging"
}

• answer is one of the options or your own words, up to 4,000 characters.
• Only the person who asked the turn can answer. For a turn asked with an API key, that person is the key's creator.
• The response's found is true when the waiting question took your answer. It is false when the question was already answered, closed, or belongs to someone else.
• The stream then sends question-end with status "answered", and the turn goes on with your answer.

A question closes with no answer when nobody answers within five minutes, when you stop the turn, or when the turn ends. The stream sends question-end with status "closed". After a timeout, the agent goes on without the answer and says what it assumed.

Message threadingCopy Anchor Link

Pass conversationId to continue an existing thread. The route loads the conversation's history for you, so you do not pass message IDs to keep it. The model reads up to the last 50 messages word for word. When a thread grows past that, Oxagen summarises the older messages into one note and sends it ahead of them, so facts from early in the thread still reach the model. The summary is stored with the conversation and rewritten about once every five turns. The run for each turn records whether it carried a summary.

Omit conversationId to start a new conversation. Read conversationPublicId from the first turn's done event and send it with later messages in the same thread.

Token usageCopy Anchor Link

The stream sends one usage event after the model calls finish. It holds the token counts for the whole turn under a usage object:

ErrorsCopy Anchor Link

A failure after the stream opened arrives as one error event, then done with [DONE]:

data: {"type":"error","message":"the assistant engine is unavailable","code":"engine_unavailable"}

event: done
data: [DONE]

An error without a stable code has the message "Stream error" and no code. To try again, send the next message with the same conversationId.

Connection handlingCopy Anchor Link

• The response sets the content-type: text/event-stream, cache-control: no-cache, and connection: keep-alive headers.
• While the turn is quiet, the stream writes an SSE comment line, : keep-alive, every 15 seconds. SSE readers skip comment lines.
• A turn with many steps can run for several minutes. Use an idle timeout longer than 15 seconds instead of a short total timeout.
• Closing the connection does not stop the turn. It runs to the end and saves its reply. Read the finished reply with POST /v1/{orgSlug}/{workspaceSlug}/assistant/reply and the body { "runId": "tse_…" }, using the runId from the run event. The response gives runStatus and, once the turn finished, reply.text.
• To stop a turn on purpose, send a turnId with the request. Then call POST /v1/{orgSlug}/{workspaceSlug}/assistant/turn/cancel with { "turnId": "…" }. The stream ends with a done event whose stopped is true and whose reply holds what the assistant wrote before the stop. The cancel response's found is false when no running turn of yours has that ID.