Integrate with the Runtime API

The Native Runs API is the primary application integration. Start a run with an agent ID. Continue it by sending the returned run ID to the same endpoint.

Discover agents

curl "$SALAMBO_BASE_URL/api/v1/agents" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"

Use the selected agent's public_id, such as agt_01J....

Start background work

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

Retrieve the run

curl "$SALAMBO_BASE_URL/api/v1/runs/run_..." \
  -H "Authorization: Bearer $SALAMBO_API_KEY"

Continue the run

curl "$SALAMBO_BASE_URL/api/v1/runs" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Idempotency-Key: continue-investigation-001" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_01J...",
    "input": "Now summarize the findings for a manager."
  }'

Cancel active work

curl -X POST \
  "$SALAMBO_BASE_URL/api/v1/runs/run_.../cancel" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Idempotency-Key: cancel-investigation-001"

Without turn_id, cancellation targets the active turn, or the queued turn when nothing is active. Run cleanup stops active sandbox work. If the run is idle, the request changes nothing and returns the latest turn.

Integration requirements

Retry policy

• Retry bounded network and upstream-unavailable failures.
• Do not retry authentication or permission failures without changing credentials.
• Do not retry invalid model or configuration errors without fixing the request or deployment.
• Use the run identifier to retrieve accepted background work.
• Cancel abandoned active work instead of deleting a non-terminal run.

Files

Turns can reference downloadable files. Use files:write for input uploads and files:read for downloads.

Sandbox-generated files appear only when the agent explicitly publishes them as runtime artifacts.

Use the API overview and generated endpoint reference for exact request and response schemas.