Get started

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.

Start a new agent run

Starts 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-Key

string

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.

message

string

in body

required

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_id

string (uuid)

in body

required

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.

profile

string

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_tools

array 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_tools

array 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.

context

object

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

AgentRun

required

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.

# The reply is the run, whose id the other agent operations take. Everything
# the run produces arrives on the event stream, not in this response. The
# Idempotency-Key makes a retried start resolve to the same run.
curl -s https://api.mountaya.com/v1/agent/runs \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Plan a three-day hut-to-hut loop from Chamonix.",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b"
  }' | jq '.data.id'
202
Response
{
  "data": {
    "id": "5f4e3d2c-1b0a-4998-8776-655443322110",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "profile": "studio",
    "created_at": "2026-10-23T08:14:52Z"
  }
}

Send an input signal into a running agent run

Delivers an input signal into a running agent run. The request body shape is selected by its type discriminator:

Path parameters

run_id

string (uuid)

in path

required

Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.

Headers

Idempotency-Key

string

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# The run asked to run a destructive tool. Approve exactly the call it named.
curl -s https://api.mountaya.com/v1/agent/runs/b6f19d02-84ae-4c37-9153-70de2ac8b4f6/input \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "confirm",
    "tool_call_id": "call_9f3c2a71",
    "approved": true
  }'

# A follow-up message into the same conversation.
curl -s https://api.mountaya.com/v1/agent/runs/b6f19d02-84ae-4c37-9153-70de2ac8b4f6/input \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"type": "user-message", "content": "Make day two shorter."}'
202
Response
{
  "data": null
}

Stream an agent run's events over Server-Sent Events

GET
/v1/agent/runs/{run_id}/events

Opens 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_id

string (uuid)

in path

required

Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.

Headers

Last-Event-ID

string

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.

# Server-Sent Events, so keep the connection open and read frames as they land.
# -N disables curl's buffering; without it nothing prints until the run ends.
curl -sN "https://api.mountaya.com/v1/agent/runs/b6f19d02-84ae-4c37-9153-70de2ac8b4f6/events" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"

# Reconnecting? Send the id of the last frame you processed and the run replays
# from just after it rather than from the beginning.
curl -sN "https://api.mountaya.com/v1/agent/runs/b6f19d02-84ae-4c37-9153-70de2ac8b4f6/events" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Last-Event-ID: 1778577393417-0"

Record the user's rating of one assistant message in a run

Records 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_id

string (uuid)

in path

required

Identifier of the agent run the operation acts on, the id of the AgentRun postAgentRun returns. It is a plain UUID.

Headers

Idempotency-Key

string

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.

rating

string

in body

required

One of: up, down

The thumb being recorded against the assistant message named by message_index.

message_index

integer (int32)

in body

required

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.

# Feedback is per MESSAGE, not per run: message_index picks which assistant turn
# the rating is about.
curl -s -X POST https://api.mountaya.com/v1/agent/runs/b6f19d02-84ae-4c37-9153-70de2ac8b4f6/feedback \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "up",
    "message_index": 2
  }'
202
Response
{
  "data": null
}