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 current active or queued turn. Run cleanup stops active sandbox work and clears queued follow-up state.

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.