Browse documentation

Deployments

Create an agent deployment

Creates an immutable deployment record. Requires agents:write.

The CLI creates the record before uploading the compiled manifest and source archive.

POST/agents/{agentId}/deployments

Authorization

AuthorizationBearer <token>

Path parameters

agentIdstringrequired

format: "uuid"

Bodyrequired

application/json

object

sourceKindstring

maxLength: 64

repositoryUrlstring | null

format: "uri"

repositoryFullNamestring | null

maxLength: 256

branchstring | null

maxLength: 256

commitShastring | null

maxLength: 128

commitUrlstring | null

format: "uri"

commitMessagestring | null

maxLength: 500

deployMessagestring | null

maxLength: 500

runtimeConfigobjectrequired

Additional properties are not allowed.

Show nested schema

sandboxRegionstring

enum: ["us","eu"]

egressPolicyModestringrequired

enum: ["restricted","full-open"]

egressAllowlistarrayrequired

maxItems: 100

Show nested schema

Array items

string

credentialExchangesobject

maxProperties: 10

Show nested schema

Additional properties

object

Additional properties are not allowed.

requestobjectrequired

Additional properties are not allowed.

Show nested schema

hoststringrequired

methodstringrequired

const: "POST"

pathstringrequired

maxLength: 2048

contentTypestringrequired

const: "application/x-www-form-urlencoded"

requiredFieldsobjectrequired

minProperties: 1
maxProperties: 8

Show nested schema

Additional properties

string

maxLength: 256

secretFieldsobjectrequired

minProperties: 1
maxProperties: 4

Show nested schema

Additional properties

string

pattern: "^[A-Z][A-Z0-9_]{0,127}$"

responseobjectrequired

Additional properties are not allowed.

Show nested schema

contentTypestringrequired

const: "application/json"

credentialFieldstringrequired

tokenTypeFieldstringrequired

expectedTokenTypestringrequired

const: "Bearer"

expiresInFieldstringrequired

accessobjectrequired

Additional properties are not allowed.

Show nested schema

allowedHostsarrayrequired

minItems: 1
maxItems: 25
uniqueItems: true

Show nested schema

Array items

string

workspaceUpgradePolicystringrequired

enum: ["automatic","new-run-only"]

otlpEndpointOverridestring | null

format: "uri"

otelIncludeContentOverrideboolean | null

sandboxImageModestringrequired

Salambo-managed immutable sandbox image.

const: "managed"

brainSummaryobject

Additional properties are allowed.

sandboxSummaryobject

Additional properties are allowed.

metadataobject

Additional properties are allowed.

Response

application/json

Created deployment

object

idstringrequired

format: "uuid"

objectstringrequired

const: "agent_deployment"

agent_idstringrequired

format: "uuid"

version_numberinteger | nullrequired

sourceobject

Show nested schema

kindstringrequired

repository_urlstring | nullrequired

repository_full_namestring | nullrequired

branchstring | nullrequired

commit_shastring | nullrequired

commit_urlstring | nullrequired

commit_messagestring | nullrequired

deploy_messagestring | nullrequired

deployed_by_user_idstring | null

format: "uuid"

source_archiveobject | null

Additional properties are allowed.

manifestobject | null

Additional properties are allowed.

imageobject | null

Additional properties are allowed.

sandbox_imageobject

Show nested schema

modestringrequired

enum: ["managed","custom"]

base_imageobject | nullrequired

Additional properties are allowed.

sandbox_regionstring | null

enum: ["us","eu",null]

runtime_configobjectrequired

Additional properties are not allowed.

Show nested schema

versionintegerrequired

const: 1

sandboxobjectrequired

Additional properties are not allowed.

Show nested schema

regionstringrequired

enum: ["us","eu"]

egressobjectrequired

Additional properties are not allowed.

Show nested schema

modestringrequired

enum: ["restricted","full-open"]

allowlistarrayrequired

maxItems: 100

Show nested schema

Array items

string

credentialExchangesobject

maxProperties: 10

Show nested schema

Additional properties

object

Additional properties are not allowed.

requestobjectrequired

Additional properties are not allowed.

Show nested schema

hoststringrequired

methodstringrequired

const: "POST"

pathstringrequired

maxLength: 2048

contentTypestringrequired

const: "application/x-www-form-urlencoded"

requiredFieldsobjectrequired

minProperties: 1
maxProperties: 8

Show nested schema

Additional properties

string

maxLength: 256

secretFieldsobjectrequired

minProperties: 1
maxProperties: 4

Show nested schema

Additional properties

string

pattern: "^[A-Z][A-Z0-9_]{0,127}$"

responseobjectrequired

Additional properties are not allowed.

Show nested schema

contentTypestringrequired

const: "application/json"

credentialFieldstringrequired

tokenTypeFieldstringrequired

expectedTokenTypestringrequired

const: "Bearer"

expiresInFieldstringrequired

accessobjectrequired

Additional properties are not allowed.

Show nested schema

allowedHostsarrayrequired

minItems: 1
maxItems: 25
uniqueItems: true

Show nested schema

Array items

string

workspaceobjectrequired

Additional properties are not allowed.

Show nested schema

upgradePolicystringrequired

enum: ["automatic","new-run-only"]

telemetryobjectrequired

Additional properties are not allowed.

Show nested schema

endpointstring | nullrequired

format: "uri"

includeContentbooleanrequired

statusstringrequired

enum: ["queued","uploading_source","source_uploaded","building_image","pushing_image","preparing_runtime","ready","failed","cancelled"]

failed_stagestring | null

brain_summaryobject

Additional properties are allowed.

sandbox_summaryobject

Additional properties are allowed.

errorobject | null

Show nested schema

codestring

messagestring

metadataobject

Additional properties are allowed.

created_atintegerrequired

updated_atintegerrequired

finished_atinteger | null

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/agents/{agentId}/deployments' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '@request.json'

Replace placeholders before running. JSON templates without a sample body read your payload from request.json.

Response

{
  "id": "<string>",
  "object": "agent_deployment",
  "agent_id": "<string>",
  "version_number": 123,
  "source": {
    "kind": "<string>",
    "repository_url": "<string | null>",
    "repository_full_name": "<string | null>",
    "branch": "<string | null>",
    "commit_sha": "<string | null>",
    "commit_url": "<string | null>",
    "commit_message": "<string | null>",
    "deploy_message": "<string | null>"
  },
  "deployed_by_user_id": "<string | null>",
  "source_archive": {},
  "manifest": {},
  "image": {},
  "sandbox_image": {
    "mode": "managed",
    "base_image": {}
  },
  "sandbox_region": "us",
  "runtime_config": {
    "version": 1,
    "sandbox": {
      "region": "us",
      "egress": {
        "mode": "restricted",
        "allowlist": [
          "<string>"
        ],
        "credentialExchanges": {}
      },
      "workspace": {
        "upgradePolicy": "automatic"
      }
    },
    "telemetry": {
      "endpoint": "<string | null>",
      "includeContent": true
    }
  },
  "status": "queued",
  "failed_stage": "<string | null>",
  "brain_summary": {},
  "sandbox_summary": {},
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "metadata": {},
  "created_at": 123,
  "updated_at": 123,
  "finished_at": 123
}