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. Set background to return after durable admission, or set stream to receive public Pi and Salambo events as Server-Sent Events.

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]+$"

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]+$"

object2

object

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

minimum: 1

statestringrequired

enum: ["idle","busy"]

dispositionstringrequired

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

turnobjectrequired

Additional properties are allowed.

Show nested schema

idstringrequired

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

objectstringrequired

const: "turn"

statusstringrequired

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

history_statusstringrequired

enum: ["available","expired"]

history_expires_atinteger | nullrequired

minimum: 0

errorunionrequired

Show nested schema

Exactly one of

null1

null

object2

object

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",
  "turn": {
    "id": "<string>",
    "object": "turn",
    "status": "queued",
    "input": [
      {}
    ],
    "output": [
      {
        "type": "output_text",
        "text": "<string>"
      }
    ],
    "created_at": 123,
    "started_at": 123,
    "completed_at": 123,
    "duration_ms": 123,
    "history_status": "available",
    "history_expires_at": 123,
    "error": null
  }
}