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

## 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.