Agent
Conversational route building. Start a run, stream its events, send it further input, and record whether its answer was useful. The agent drives the same operations a person would; it has no privileged surface of its own.
/v1/agent/runsStarts a new agent run for the user the session token names. The run is created and then continues on its own: this call returns as soon as it has an identifier, live output arrives over the run's event stream (getAgentRunEvents), and follow-up input is sent to the running conversation (postAgentRunInput).
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The resource the run is opened on, the model profile to drive it, and the client-side tool manifest the model may call. The studio snapshot, if sent, seeds the transcript with the current state of the studio the run is opened from.
messagestring
in body
The user's first message that opens the conversation. It is trimmed before it is validated, so a message of only whitespace is rejected: it would otherwise start a run and spend a provider turn on nothing. The upper bound exists because this message is kept for the run's whole life and replayed on every continuation.
organization_idstring (uuid)
in body
The organization the run belongs to, which owns the resource the co-pilot is opened on. It must be the key's organization. The user the session token names must hold a write role in it, and its AI provider configuration is what drives the model.
profilestring
in body
default: studio
One of: studio, video-director
Which prompt profile to seed the run with. The agent serves several surfaces and each has to be told which tools it actually holds, so this is chosen at creation and fixed for the life of the run. Omitted, it is studio.
client_toolsarray of AgentClientToolManifest
in body
The browser's contextual client-tool schemas for this run. Merged with the server tools into the schema list handed to the model; a client tool may not shadow a server tool.
server_toolsarray of string
in body
Names of the server tools the routed surfaces permit for this run. Omitted, the model sees every server tool; present, the schema list handed to the model carries only the named ones. Names that are not server tools are ignored, so the caller may pass its whole routed tool set. Advisory over what the model can SEE, exactly like the client manifest; execution authorization is unchanged.
contextobject
in body
The caller's point-in-time studio snapshot, captured once by the browser at run start (active itinerary, current selection, enabled overlays, viewport, unit/locale preferences, and the available-overlay catalog). Its inner shape is not typed here (the client that builds it owns that), and it is passed through as sent with one exception: the overlay list at catalog.overlays is dropped, since the model can list overlays itself. It is surfaced to the model as a read-only system message seeding the transcript, so the run starts knowing the current UI state. It is never re-read mid-run. At most 32 top-level fields and 32 KiB as sent; over either is a 400 naming context.
Response 202
Accepted: the run is started and continues on its own. data is the run, whose id the input, events and feedback operations take as their run_id. A retried start with the same Idempotency-Key is answered this same run.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataAgentRun
An agent run that postAgentRun started. The run itself happens after the answer: its events are read from getAgentRunEvents, which opens on the run's id.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/agent/runs/{run_id}/inputDelivers an input signal into a running agent run. The request body shape is selected by its type discriminator:
Path parameters
run_idstring (uuid)
in path
Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The signal to deliver to a waiting run: a user message, a confirmation, a client tool's result, an updated tool manifest, or a close.
Response 202
Accepted. A tool-result, confirm or manifest-update sent to a run that has ended, or answering a call already given up on, is accepted and dropped.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/agent/runs/{run_id}/eventsOpens a Server-Sent Events (SSE) stream of the run's live output. The response Content-Type is text/event-stream and the connection stays open until the run reaches its terminal done event, the credential it was opened with ends, the member's hold on the run is lost, the server cannot keep delivering it, or the client disconnects.
Path parameters
run_idstring (uuid)
in path
Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.
Headers
Last-Event-IDstring
in header
The last stream id the client received, <milliseconds>-<sequence> as the stream wrote it, for example 1778577393417-0. A value of any other shape is a 400, answered before the stream opens. When set, the server replays the events after that id that the stream still holds before resuming the live feed. A stream holds about its last thousand events, for an hour after the latest one, or for five minutes after an agent run's done event, so a client that reconnects within that window misses no event that carries an id. An id older than what the stream still holds is not refused: the replay starts at the oldest event held, and nothing marks the gap.
Response 200 text/event-stream
A text/event-stream of the run's events, framed as id:/event:/data: records, terminated by a done event, save for a run stopped from outside, whose stream closes without one; a stream whose credential ends first, or that the server cannot keep delivering, which closes after a reconnect event; and a stream whose member loses their hold on the run, which closes after a : session-ended comment, a comment and not an event. The schema describes one decoded frame, the data: JSON of a single record, not the byte stream as a whole.
Errors 400, 401, 402, 403, 404, 409, 429, 500, 503. See Errors.
/v1/agent/runs/{run_id}/feedbackRecords a thumbs up or thumbs down against one assistant message. It is the explicit outcome label for the run: the tool sequence already implies whether the work was taken up, but only for runs that ended in an edit, and says nothing about a run that ended in an answer.
Path parameters
run_idstring (uuid)
in path
Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The rating for one assistant message in the run, identified by its zero-based index in the conversation.
ratingstring
in body
One of: up, down
The thumb being recorded against the assistant message named by message_index.
message_indexinteger (int32)
in body
Zero-based index of the rated assistant message within the run's conversation. A run carries several answers, and a rating on the third is not a verdict on the first.
Response 202
Accepted: the rating is recorded beside any this user gave the same message before, and as the latest press it is the one that counts.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.