v1

latestOpenAPI 3.1.02026-08-04151221521.2 KB

Branches

Agents

Deploy Agent

Deploy an agent to the platform.

Called by CLI after pushing the container image to the registry.
Creates or updates agent, branch, and version records.

The deployment is asynchronous - poll GET /branches/{branch_id}
for status updates until status is READY or FAILED.

**Flow:**
1. CLI builds and pushes image to registry (using /registry/auth)
2. CLI calls POST /agents/deploy with image details
3. Platform creates records and triggers K8s deployment
4. Container starts and calls POST /versions/register
5. CLI polls GET /branches/{id} for status

post/agents/deploy

Request body

acp_type'sync' | 'async'

Type of ACP server.

agent_namestring required

Agent name in 'namespace_slug/agent_name' format (lowercase alphanumeric, hyphens, underscores)

are_tasks_stickyboolean nullable

If true, running tasks stay on their original version until completion during this deploy. If false or None, tasks are migrated to the new version immediately.

author_emailstring required

Git commit author email

author_namestring required

Git commit author name

branchstring required

Git branch name (e.g., 'main', 'feature/new-tool')

descriptionstring nullable

Agent description (used when creating new agent)

git_hashstring required

Git commit hash (short or full)

git_messagestring nullable

Git commit message (truncated if too long)

image_urlstring required

Full container image URL (e.g., 'us-east4-docker.pkg.dev/proj/repo/agent:hash')

is_dirtyboolean

Whether the working directory had uncommitted changes at deploy time

replicasinteger

Desired replica count (1-10)

resourcesobject nullable

Resource requests and limits (e.g., {'requests': {'cpu': '100m', 'memory': '256Mi'}, 'limits': {'cpu': '1000m', 'memory': '1Gi'}})

sdk_type'claude_agent_sdk' | 'codex_agent_sdk'

SDK type for agent runtime.

source_filesystem_idstring nullable

Filesystem snapshot containing the deploy source for Builder reopenability

Response

Successful Response

agent_idstring required

Agent ID (created or existing)

branch_idstring required

Branch ID for this git branch

messagestring required

Human-readable status message

tasks_migratedinteger nullable

Number of tasks migrated from old version (if any)

version_idstring required

New version ID

Status of a version in its lifecycle.