Agents and deployments API

Use these endpoints to manage stable agent identity, immutable deployments, and runtime history.

Agent availability is active or inactive. Set isActive when you create or update an agent. Agent objects expose is_active. Active agents that satisfy runtime prerequisites can accept new native runs.

List agents

GET /api/v1/agents

Required scope:

agents:read

Archived agents return 404 and are not projected as inactive resources.

curl "$SALAMBO_BASE_URL/api/v1/agents?limit=20" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"

Query parameters:

Archived agents are excluded from the list.

Create an agent

POST /api/v1/agents

Required scope:

agents:write

curl "$SALAMBO_BASE_URL/api/v1/agents" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Demo Agent",
    "description": "Runs documentation smoke tests.",
    "isActive": false
  }'

Request body:

Response objects include:

{
  "id": "uuid",
  "public_id": "agt_01J...",
  "object": "agent",
  "name": "Docs Demo Agent",
  "slug": "docs-demo-agent",
  "description": "Runs documentation smoke tests.",
  "is_active": false
}

Get an agent

GET /api/v1/agents/{agentId}

Required scope:

agents:read

Update an agent

PATCH /api/v1/agents/{agentId}

Required scope:

agents:write

curl -X PATCH "$SALAMBO_BASE_URL/api/v1/agents/YOUR_AGENT_ID" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated purpose.",
    "isActive": true
  }'

At least one update field is required.

Archived agents return 404 and cannot be updated or reactivated.

Archive an agent

DELETE /api/v1/agents/{agentId}

Required scope:

agents:write

This archives the agent and sets is_active to false.

Agent deployments

GET /api/v1/agents/{agentId}/deployments
POST /api/v1/agents/{agentId}/deployments

Deployments are immutable versions. Source deployment normally uses the CLI, which creates the deployment, attaches the compiled manifest, uploads the source archive, and waits for the hosted deployment worker.

Deployment objects identify source provenance through source.commit_sha and sandbox-image provenance through sandbox_image. Provider-owned preparation identifiers are not part of the public contract.

Deployment runtime configuration

Runtime policy is captured when the deployment is created. It is immutable with that deployment and is not stored as mutable agent state.

The create request includes:

{
  "sandboxImageMode": "managed",
  "runtimeConfig": {
    "sandboxRegion": "eu",
    "egressPolicyMode": "restricted",
    "egressAllowlist": ["api.openai.com"],
    "workspaceUpgradePolicy": "automatic",
    "otlpEndpointOverride": null,
    "otelIncludeContentOverride": false
  }
}

Deployment responses expose the resolved immutable value as runtime_config. When sandboxRegion is omitted, the workspace default is resolved and stored during deployment creation.

There is no agent-level runtime endpoint. To change region, egress, workspace-upgrade, or telemetry policy, create a new deployment and activate it after it becomes ready.

Activate a deployment version

The deployment worker automatically activates a newly completed source deployment. Use the explicit activation endpoint when you need to make any other ready deployment active:

POST /api/v1/agents/{agentId}/deployments/{deploymentId}/activate

The selected deployment can be older or newer than the currently active version, but it must already be ready. Activating an older version is a rollback for future runs; existing durable runs are unchanged.

Use the Runs API to start, continue, inspect, stream, cancel, or delete agent work.