Use these endpoints to manage stable agent identity, immutable deployments, and runtime history. Agent availability is active or inactive. Set isActive when creating or updating an agent. Responses expose the resulting is_active value, and active agents that satisfy runtime prerequisites appear in GET /api/v1/models.

​
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:
ParameterTypeNotes
limitnumber1-100, defaults to 50.
afterUUIDPagination cursor.
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:
FieldTypeRequiredNotes
namestringyesRequired, max 100 characters.
descriptionstring or nullnoMax 500 characters.
iconstring or nullnoMax 10 characters.
commandContentstringnoAgent instructions. A default template is used if omitted.
isActivebooleannoActive/inactive switch. Defaults to false when creating.
Response objects include: 
{
  "id": "uuid",
  "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.

​
List runs

GET /api/v1/runs
Required scope: 
runs:read

curl "$SALAMBO_BASE_URL/api/v1/runs?agent_id=YOUR_AGENT_ID&agent_version_number=3&limit=20" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"
Omit agent_id to list runs across the API key’s workspace. Combine agent_id with agent_version_number to filter by one immutable deployment version. Without agent_id, the version filter matches every agent in the workspace that shares that version number. The optional status, after, and limit parameters use the same account-scoped collection.

​
Get run status

GET /api/v1/runs/{runId}
Required scope: 
runs:read
Run objects include status, agent ID, immutable deployment ID and version, runtime type, sandbox state, timestamps, duration, and error details when present.

​
Cancel a run

POST /api/v1/runs/{runId}/cancel
Required scope: 
runs:write
Terminal runs cannot be cancelled. Terminal statuses are:
  • completed
  • failed
  • cancelled

​
Delete a terminal run

DELETE /api/v1/runs/{runId}
Required scope: 
runs:write
Only terminal runs can be deleted. Non-terminal runs return 409 conflict with guidance to cancel first.