Browse documentation

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

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

export SALAMBO_API_KEY="sk_..."

All API requests use bearer-token authentication:

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

{
  "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.

Up nextCreate an API key