Skip to main content
POST
Generate report and stream response

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Scopes

agent:write

agent:write

Path Parameters

project_id
string
required

Body

application/json
message
string
required

User message to send to the Summation agent.

Minimum string length: 1
display_content
string | null

Optional alternate rendering of the message for display; the agent still receives message.

file_ids
string[]

Project file ids to attach to the message as context.

mentioned_file_ids
string[]

Project file ids referenced inline in the message.

model
string | null

Chat model id to use for this turn, from GET /v1/chat-models. Per-request model selection is honored where enabled for the tenant; otherwise the default model applies. The reply metadata reports the model that ran.

Minimum string length: 1
effort
enum<string> | null

Reasoning effort for this turn (low, medium, high, xhigh, max). Honored under the same tenant setting as model selection; otherwise the default effort applies.

Available options:
low,
medium,
high,
xhigh,
max
title
string | null

Optional conversation title; derived from the message when omitted.

Response

Server-Sent Events stream of agent activity.

Each event is a UTF-8 line prefixed with event:, id:, or data: per the SSE spec. The data: payload is a JSON object with the shape {"type": <event_type>, "sequence": <int>, "data": <object>}.

Event types emitted by the agent:

  • status — high-level progress; data.message (queued/running text) or data.summary (short status line). When the conversation was busy and the message was queued (request field on_busy: "queue"), the first event is status with data.message: "queued" (or "held" if a Stop has already paused the queue), data.queuedMessageId, data.position, data.behindMessageId, data.held, and data.revision; the reply then streams once the queued turn dispatches. A held queue does not run until it is resumed.
  • queue.updated — the waiting message's queue state changed; data.position, data.held, data.revision, data.queuedMessageId. held: true means a Stop paused the queue: the message will not run until the queue is resumed (POST .../queue/resume). revision only moves forward; ignore any snapshot older than one you hold.
  • tool.started — agent invoked a tool; data.id, data.name
  • tool.input — tool input arguments; data.id, data.name, data.input
  • tool.completed — tool finished; data.id
  • message.delta — incremental assistant text; data.text (append in order)
  • done — terminal event; data.messageId, data.content (final assistant message), data.status (complete / error / cancelled)
  • error — terminal error; data.code, data.message. A queued message may end with code: "queue_wait_timeout" after 30 minutes of waiting — the message is still queued and can be observed again via the queue endpoints.

Resumability: when the connection drops before done, the same stream can be resumed via GET /v1/projects/{project_id}/conversations/{chat_id}/messages/{message_id}/events. Before a queued message has bound an assistant message id, reconnect by re-sending with the same idempotency_key, or poll GET /v1/projects/{project_id}/conversations/{chat_id}/queue/{queued_message_id}.