Runs API

The Runs API is the application-facing execution API. A run keeps the pinned agent version, trusted Pi session, and durable workspace across turns.

Start a run

POST /api/v1/runs

Required scope: run:write.

curl "$SALAMBO_BASE_URL/api/v1/runs" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Idempotency-Key: start-report-001" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agt_01J...",
    "input": "Write a short status report.",
    "background": true
  }'

Supply exactly one selector:

• agent starts a new run;
• run_id continues an existing run.

The default delivery waits for the affected turn. Set background to return after durable admission, or set stream to receive Server-Sent Events. Do not set both fields to true.

Continue a run

Use the same endpoint with the existing run ID:

{
  "run_id": "run_01J...",
  "input": "Revise the report for an executive audience.",
  "on_busy": "queue"
}

on_busy accepts:

Send text and files

input can be a string or an array of typed parts:

{
  "run_id": "run_01J...",
  "input": [
    { "type": "input_text", "text": "Review this invoice." },
    { "type": "input_file", "file_id": "file_01J..." }
  ]
}

Upload larger input files through POST /api/v1/files. Small files can be sent inline with filename and base64 file_data.

Read run and turn state

GET /api/v1/runs/{runId}
GET /api/v1/runs/{runId}?turn_id=turn_...

Required scope: run:read.

Without turn_id, the endpoint selects the latest turn. The returned object contains the run state and the selected turn:

{
  "id": "run_01J...",
  "object": "run",
  "agent_id": "agt_01J...",
  "agent_version": 7,
  "state": "idle",
  "disposition": "created_run",
  "turn": {
    "id": "turn_01J...",
    "object": "turn",
    "status": "completed",
    "input": [],
    "output": [{ "type": "output_text", "text": "..." }],
    "error": null
  }
}

Read retained events

GET /api/v1/runs/{runId}/events

The event list contains public Pi events and Salambo platform events in run sequence order. Use turn_id to select one turn, after to continue from an event cursor, and limit to set the page size.

The full event stream is encrypted before Salambo writes it to S2. Postgres stores the bounded run and turn read model. It does not store the full event payload history.

Consumers must accept unknown event types and additive data fields. Use source and type as discriminators.

Cancel work

POST /api/v1/runs/{runId}/cancel

Use an empty body to target current work. Supply turn_id to cancel one active or queued turn. Active cancellation can return 202 while the runtime settles.

Delete an idle run

DELETE /api/v1/runs/{runId}

Deletion fences new work and starts asynchronous cleanup. A busy run must be cancelled and allowed to settle before deletion.

Idempotency

All mutating endpoints require an Idempotency-Key header. Reuse a key only when you retry the same operation.