Browse documentation

Runs

Start or continue a run

Start a run with agent, or continue a run with run_id. Supply exactly one selector. Requires run:write and an idempotency key.

By default, the request waits for the affected turn, for up to 120 seconds. It answers 200 if the turn is final by then and 202 if it is not. Set background to return after durable admission, or set stream to receive public Pi and Salambo events as Server-Sent Events.

A new run starts on the agent's active deployment. Add version to agent to start it on exactly that deployment version instead, without activating it. The run's first turn executes on that version and reports it as agent_version. version is only accepted with agent, never with run_id: a run started on an exact version runs its first turn on that version, and later turns follow the agent's workspace-upgrade policy, which either moves the run to the agent's active deployment before its next turn (automatic) or keeps it where it is (new-run-only). Repeating a request with the same idempotency key returns the same turn on the same version.

A version the agent has never had returns 404 with code agent_version_not_found. A version that exists but is not ready to run returns 409 with code agent_version_not_ready. Both name version in error.param.

Add tags to agent to label the new run. tags is only accepted with agent, never with run_id: change the tags of a run that already exists with POST /runs/{runId}/tags. A request with run_id and tags returns 400 naming tags. Repeating a request with the same idempotency key and the same tags returns the same run, and the same key with other tags returns 409 with code idempotency_conflict. The order of the tags and repeated tags do not make a request different.

An input sent with on_busy set to steer to a turn that ended before the input was stored returns 409 with code steering_target_ended. The input was not taken. Send it again with a new idempotency key: the same key returns the same answer.

POST/runs

Authorization

AuthorizationBearer <token>

Headers

Idempotency-Keystringrequired

minLength: 1
maxLength: 255

Last-Event-IDstring

pattern: "^evt_[a-f0-9]{12}x[a-z0-9]+$"

Bodyrequired

application/json

object

Additional properties are not allowed.

agentstring

pattern: "^agt_[A-Za-z0-9]+$"

versioninteger

A deployment version number of the agent, the same number every run reports as agent_version. Starting a run on it does not activate it. Only accepted with agent.

minimum: 1
maximum: 2147483647

tagsarray

Up to 20 tags. A repeated tag is one tag, and the order does not matter.

maxItems: 20

Show nested schema

Array items

string

A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.

minLength: 1
maxLength: 64
pattern: "^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"

run_idstring

pattern: "^run_[A-Za-z0-9]+$"

inputunionrequired

Show nested schema

Exactly one of

string1

string

minLength: 1

array2

array

minItems: 1

Array items

union

Exactly one of

object1

object

Additional properties are not allowed.

typestringrequired

const: "input_text"

textstringrequired

minLength: 1

object2

object

Additional properties are not allowed.

typestringrequired

const: "input_file"

file_idstringrequired

pattern: "^file_[A-Za-z0-9]+$"

object3

object

Additional properties are not allowed.

typestringrequired

const: "input_file"

filenamestringrequired

minLength: 1
maxLength: 255

file_datastringrequired

contentEncoding: "base64"
maxLength: 349528

on_busystring

enum: ["queue","steer","reject"]
default: "queue"

streamboolean

default: false

backgroundboolean

default: false

All of these rules apply

union1

union

Exactly one of

object1

object

agentstringrequired

pattern: "^agt_[A-Za-z0-9]+$"

versioninteger

A deployment version number of the agent, the same number every run reports as agent_version. Starting a run on it does not activate it. Only accepted with agent.

minimum: 1
maximum: 2147483647

tagsarray

Up to 20 tags. A repeated tag is one tag, and the order does not matter.

maxItems: 20

Show nested schema

Array items

string

A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.

minLength: 1
maxLength: 64
pattern: "^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"

run_idnever

object2

object

agentnever

versionnever

tagsnever

run_idstringrequired

pattern: "^run_[A-Za-z0-9]+$"

Response

The selected turn reached a terminal state, or an event stream opened.

object

Additional properties are allowed.

idstringrequired

pattern: "^run_[A-Za-z0-9]+$"

objectstringrequired

const: "run"

agent_idstringrequired

pattern: "^agt_[A-Za-z0-9]+$"

agent_versionintegerrequired

The deployment version that executes the returned turn. It equals turn.agent_version.

minimum: 1

statestringrequired

enum: ["idle","busy"]

dispositionstringrequired

enum: ["created_run","created_turn","queued_turn","steered"]

tagsarrayrequired

The run's tags, sorted, without repeats. A run has at most 20.

maxItems: 20
uniqueItems: true

Show nested schema

Array items

string

A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.

minLength: 1
maxLength: 64
pattern: "^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"

turnobjectrequired

Additional properties are allowed.

Show nested schema

idstringrequired

pattern: "^turn_[A-Za-z0-9]+$"

objectstringrequired

const: "turn"

agent_versionintegerrequired

The deployment version of the agent that executes this turn. It is pinned when the turn is admitted and never changes, so it still names the version that ran after the agent's active version moves on. A run can hold turns on different versions.

minimum: 1

statusstringrequired

completed, failed, cancelled and incomplete are final. completed returns its complete result and no error. failed is described by error. cancelled has empty output and no error. incomplete keeps the partial output it produced, and error explains why it stopped when the runtime reported a reason (otherwise null). cancelling means a cancellation was accepted and the runtime is cleaning up.

enum: ["queued","in_progress","cancelling","completed","failed","cancelled","incomplete"]

inputarrayrequired

Show nested schema

Array items

object

Additional properties are allowed.

outputarrayrequired

Show nested schema

Array items

union

Exactly one of

object1

object

Additional properties are allowed.

typestringrequired

const: "output_text"

textstringrequired

object2

object

Additional properties are allowed.

typestringrequired

const: "output_file"

file_idstringrequired

filenamestringrequired

media_typestringrequired

created_atintegerrequired

minimum: 0

started_atinteger | nullrequired

minimum: 0

completed_atinteger | nullrequired

minimum: 0

duration_msinteger | nullrequired

minimum: 0

errorunionrequired

Why a failed turn stopped (always present), or why an incomplete turn stopped when the runtime reported a reason (otherwise null). null for every other status. It is stored with the turn and stays available regardless of event retention.

Show nested schema

Exactly one of

null1

null

object2

object

The structured reason a turn stopped by error. code is a stable machine-readable reason and new codes can be added. retryable says whether sending the same work again can succeed. reference identifies the failure for support.

Additional properties are allowed.

codestringrequired

sourcestringrequired

enum: ["provider","extension","runtime","platform","configuration"]

messagestringrequired

retryablebooleanrequired

referencestringrequired

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/runs' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": "agt_example",
  "input": "Summarize the project README."
}'

Replace placeholders with your values.

Response

{
  "id": "<string>",
  "object": "run",
  "agent_id": "<string>",
  "agent_version": 123,
  "state": "idle",
  "disposition": "created_run",
  "tags": [
    "<string>"
  ],
  "turn": {
    "id": "<string>",
    "object": "turn",
    "agent_version": 123,
    "status": "queued",
    "input": [
      {}
    ],
    "output": [
      {
        "type": "output_text",
        "text": "<string>"
      }
    ],
    "created_at": 123,
    "started_at": 123,
    "completed_at": 123,
    "duration_ms": 123,
    "error": null
  }
}