Skip to main content
POST
Run network

Authorizations

Authorization
string
header
required

Session token (snat_…) minted by POST /v1/token. Carries the organization and the end user; safe in a browser.

Path Parameters

id
string
required

Network (copilot) id.

Example:

"a5e91c07-3f24-4b68-9d15-8c72e0b4a396"

Body

application/json
messages
array

The conversation, in AI SDK UIMessage format: [{ "role": "user", "parts": [{ "type": "text", "text": "..." }] }]. Send the whole exchange you want the agent to see; with a threadId the stored history is loaded too, so the new turn is usually the only entry. May be empty only on an approval continuation.

Example:
approval
object

Continue a tool call that paused the previous stream: approve/decline it, or answer a suspended tool with data

Example:
environment
enum<string>

The environment this request runs in, recorded on its traces and usage. Defaults to the copilot's environment for routed requests, else dev.

Available options:
dev,
staging,
prod
threadId
string

Conversation thread id

Example:

"thread_2f81c04a"

context
string[]

Additional context messages to provide to the agent.

Example:
variables
object

Values for {{variable}} placeholders in the agent's prompt blocks. Scalars (string, number, boolean) or arrays of them. A dot path up to 3 segments may be sent nested or as a dotted key — { "user": { "language": "FR" } } and { "user.language": "FR" } both fill {{user.language}}. This is the shape GET /v1/copilots/{id} and GET /v1/agents/{id} return under variables: fill in the leaves you have and send the object back. A null leaf is ignored (the placeholder falls back to its own default), so leaving one unfilled is the same as omitting it. Display-only — never used for authorization or identity. Reserved: now.*. Entries with an unsupported key or value are dropped, not rejected: a display-only field must not fail a chat turn.

Example:
trigger
enum<string>

AI SDK trigger type

Available options:
submit-message,
regenerate-message
tools
object

AI SDK client-side tools

Example:
metadata
object

AI SDK session metadata

Example:
use_routing
boolean
default:true

Default true. When the request targets an orchestrator agent, routing picks whether to stream the orchestrator (multi-step / synthesis) or a single subagent directly (domain-specific ask). No effect when the resolved agent is not an orchestrator. Pass false to disable.

suggest_followups
boolean
default:true

Default true. After the answer finishes streaming, a small model proposes up to 3 questions the user could ask next, emitted as a data-followups chunk for the client to render as chips. Costs one extra model call per turn and holds the stream open slightly longer — pass false to disable. Only applies to copilotId requests: an agentId run has no UI to render chips into, so suggestions never run there.

mode
enum<string>

dashboard marks a conversation that lives in the Dashboards section (the new-dashboard view, or an open dashboard): the thread is stamped with the dashboard it is about (dashboardId) or, when it has none yet, with the dashboard the turn builds, so it becomes that dashboard's conversation. It changes nothing about who answers: the roster answers every turn and delegates dashboard work to the dashboard agent. Without it, a dashboard built from an ordinary conversation is not tied to that thread.

Available options:
dashboard
dashboardId
string<uuid>

The dashboard the user is looking at (/v1/dashboards). The agent that answers gets its current data in context — to answer questions about it and to brief the dashboard agent for a change — and the thread is stamped with it, so follow-ups need no id. Omit when the conversation is not about a dashboard.

delivery
object

For a caller that relays answers itself (a messaging channel). Names the tool that relays the result of a SCHEDULE created during this turn: the schedule copies it, and after each of its runs — succeeded or failed — the tool is called as the schedule's owner, with their stored tool credentials, with { ...input, [result_key]: { text, attachments, run_id, schedule_id, automation_name, status, error } }. This run itself does nothing with it: you relay its answer as usual. The agent never sees the field and cannot change it.

automation_confirmation
enum<string>
default:card

How the user approves an automation the agent builds in this turn. card (default): the turn pauses on the workflow card (data-tool-call-suspended), which a chat UI shows with Test and Approve. text: for a channel that cannot show a card — the agent says in words what will be sent and when, the user replies yes in a later message (same threadId), and only then is the automation saved and scheduled. The turn never pauses.

Available options:
card,
text

Response

The finished turn

threadId
string

The conversation this turn belongs to — the one you sent, or the one created for you. Send it back on the next call to continue.

requestId
string | null

Correlation id for this run; the join key for its traces and cost.

text
string

The agent's answer. When a step of the turn was redone (a data-step-redo part in data), only what the agent wrote after the redo: the text it withdrew is not part of the answer.

reasoning
string

Reasoning text, when the model emitted any. Absent otherwise.

toolCalls
object[]

The tools the agent called, in order, each with its input and either its output or the error it failed with.

data
object[]

Custom parts the run emitted: data-handoff (which agent a network routed to), data-tool-workflow (workflow step progress), data-tool-progress-message (the one-line progress message of a tool call, for a live UI), data-step-redo (the agent's reply was rejected by a platform check and written again; text holds the final one), and data-tool-call-approval — that last one means the run PAUSED for human approval rather than finishing. Call again with approval and the same threadId to continue it.

errors
string[]

Errors the run reported. A turn can fail after it began answering, so this can be non-empty alongside text — and the status is still 200, because the same failure over /v1/chat happens long after the headers.

finishReason
string