# API overview

Salambo API v1 authentication, primary resources, control-plane endpoints, and errors.

API v1 is the programmatic control plane for Salambo workspaces.

## Base URL

```bash
export SALAMBO_BASE_URL="https://YOUR_SALAMBO_BASE_URL"
```

Use the base URL for your Salambo environment. For hosted production docs, replace this with the stable Salambo API/app domain provided by your workspace administrator.

## Authentication

```bash
export SALAMBO_API_KEY="sk_..."
```

All API requests use bearer-token authentication:

```http
Authorization: Bearer $SALAMBO_API_KEY
```

Keys use:

* `sk_live_` for live mode;
* `sk_test_` for test mode.

## Primary resources

| Resource    | Purpose                                          |
| ----------- | ------------------------------------------------ |
| Models      | Discover active agent slugs                      |
| Runs        | Start, continue, stream, inspect and cancel work |
| Agents      | Manage stable agent identity and active state    |
| Deployments | Create and inspect immutable agent versions      |
| Environment | Manage agent configuration and secrets           |
| Files       | List and download authorized files and artifacts |
| API keys    | Create, rotate and revoke scoped authority       |

Deployment creation captures runtime region, egress, workspace-upgrade, and telemetry policy. Agents do not expose a separate mutable runtime-settings resource.

## Common execution endpoints

| Endpoint                             | Scope         | Use                     |
| ------------------------------------ | ------------- | ----------------------- |
| `GET /api/v1/models`                 | `models:read` | List active agent slugs |
| `POST /api/v1/runs`                  | `run:write`   | Start or continue a run |
| `GET /api/v1/runs`                   | `run:read`    | List workspace runs     |
| `GET /api/v1/runs/{runId}`           | `run:read`    | Inspect a run and turn  |
| `GET /api/v1/runs/{runId}/events`    | `run:read`    | Read retained events    |
| `POST /api/v1/runs/{runId}/cancel`   | `run:write`   | Cancel run work         |
| `DELETE /api/v1/runs/{runId}`        | `run:write`   | Delete an idle run      |
| `POST /api/v1/files`                 | `files:write` | Upload an input file    |
| `GET /api/v1/files`                  | `files:read`  | List files              |
| `GET /api/v1/files/{fileId}/content` | `files:read`  | Download file content   |

## Deployment endpoints

| Endpoint                                                            | Scope          | Use                                   |
| ------------------------------------------------------------------- | -------------- | ------------------------------------- |
| `GET /api/v1/agents/{agentId}/deployments`                          | `agents:read`  | List immutable versions               |
| `POST /api/v1/agents/{agentId}/deployments`                         | `agents:write` | Create a deployment record            |
| `POST /api/v1/agents/{agentId}/deployments/{deploymentId}/manifest` | `agents:write` | Attach the compiled manifest          |
| `POST /api/v1/agents/{agentId}/deployments/{deploymentId}/source`   | `agents:write` | Upload source and queue the build     |
| `POST /api/v1/agents/{agentId}/deployments/{deploymentId}/activate` | `agents:write` | Explicitly activate any ready version |

## Environment and key management

| Endpoint                                               | Scope             | Use                                     |
| ------------------------------------------------------ | ----------------- | --------------------------------------- |
| `GET /api/v1/agents/{agentId}/env-vars`                | `env_vars:read`   | List environment metadata               |
| `PUT /api/v1/agents/{agentId}/env-vars/{name}`         | `env_vars:write`  | Store configuration or a secret         |
| `DELETE /api/v1/agents/{agentId}/env-vars/{name}`      | `env_vars:write`  | Delete a value                          |
| `POST /api/v1/agents/{agentId}/env-vars/{name}/reveal` | `env_vars:reveal` | Reveal a secret through an audited path |
| `GET /api/v1/api-keys`                                 | `api_keys:manage` | List API keys                           |
| `POST /api/v1/api-keys`                                | `api_keys:manage` | Create a key                            |
| `POST /api/v1/api-keys/{keyId}/rotate`                 | `api_keys:manage` | Rotate a key                            |
| `POST /api/v1/api-keys/{keyId}/revoke`                 | `api_keys:manage` | Revoke a key                            |

## Error shape

```json
{
  "error": {
    "message": "Missing scope run:write",
    "type": "permission_error",
    "param": null,
    "code": "permission_denied"
  }
}
```

Use the generated API Reference for exact schemas, parameters and response objects.