# Integrate with the Runtime API

Start and continue durable agent runs from your application.

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

```bash
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

```bash
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

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

## Continue the run

```bash
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

```bash
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

| Requirement    | Check                                      |
| -------------- | ------------------------------------------ |
| Authentication | Valid account-scoped bearer key            |
| Scope          | `agents:read`, `run:read`, and `run:write` |
| Agent          | Active and owned by the key's workspace    |
| Deployment     | Ready active deployment                    |
| Runtime        | Billing and provider configuration ready   |

## 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](/docs/api/overview) and generated endpoint reference for exact request and response schemas.