Deployment API

Use the Platform API for release automation from CI, coding agents, and scripts. The API reference lists supported endpoints, token kinds, and documented request bodies.

Credentials

Authenticate deployment calls with a pk_ platform automation token. An ak_ agent runtime key authorizes runtime calls and cannot control deployments.

Create tokens in organization settings while signed in. Automation tokens cannot create or revoke other automation tokens. Prefer an agent-bound operator token for routine releases.

The examples use these environment variables:

export AMODAL_API_BASE=https://api.amodalai.com
export AMODAL_AGENT_ID="YOUR_AGENT_ID"
# Set AMODAL_PLATFORM_TOKEN from your secret manager.

For complete agent setup, see Build With A Coding Agent.

Source And Build

A deployment builds the agent's selected source. For a connected GitHub or GitLab repository, publish changes to the branch you want to deploy. For Amodal-hosted source, save a source version first.

Start a preview build with POST /api/deployments/redeploy:

curl --fail-with-body "$AMODAL_API_BASE/api/deployments/redeploy" \
  -H "Authorization: Bearer $AMODAL_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"'"$AMODAL_AGENT_ID"'","branch":"main","environment":"preview"}'

Use a branch or source ref that exists for the agent. The response returns deployId and buildId. Poll GET /api/deployments/{deployId} for deployment status and GET /api/builds/{buildId}/status for build progress. Build logs are available at GET /api/builds/{buildId}/logs.

A completed build and an active deployment are separate states. Check runtime readiness and isActive before proceeding. Builds targeting production activate automatically only when automatic production promotion is enabled in the agent's deploy settings; it is disabled by default. With manual promotion, a completed production build stays inactive until you activate it. Builds targeting preview environments activate automatically.

Test And Activate

Test the immutable deploy URL before changing production. For runtime chat tests, mint a short-lived runtime token with POST /api/agents/{agent_id}/tokens and use it as the bearer token for /chat/stream. A pk_ token cannot authorize runtime chat. See Authentication.

To activate a specific deploy in its existing environment, call POST /api/deployments/{deployId}/activate. This deactivates the current deploy in that environment. It does not copy a preview deploy into production.

Promote Between Environments

POST /api/deployments/promote copies the active deployment from one environment into a separate deployment in another environment and activates the result:

curl --fail-with-body "$AMODAL_API_BASE/api/deployments/promote" \
  -H "Authorization: Bearer $AMODAL_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"'"$AMODAL_AGENT_ID"'","fromEnvironment":"preview","toEnvironment":"production"}'

Confirm that the source environment's active deployment is the one you tested. Its runtime bundle must still be available in artifact storage. If the bundle is missing or cannot be copied, promotion fails without changing the active destination deployment. The promoted deployment has its own ID and runtime lifecycle. This explicit release action activates the destination regardless of the automatic production promotion setting.

For GitHub source, a pending or failing amodal/evals commit status blocks promotion with EVAL_GATE_BLOCKED. A missing check does not block it. The API accepts force: true to override the check; see Evals.

Roll Back

Pass the deployment ID you want to activate in the target environment:

curl --fail-with-body "$AMODAL_API_BASE/api/deployments/rollback" \
  -H "Authorization: Bearer $AMODAL_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"'"$AMODAL_AGENT_ID"'","deployId":"'"$KNOWN_GOOD_DEPLOY_ID"'","environment":"production"}'

Without deployId, rollback selects the second-most-recent deployment by creation time in that environment. It does not select by test result or activation history. Use an explicit ID for a verified release.

Runtime URLs

Production activation or rollback changes the persistent URL's destination. A deploy URL stays pinned to its ID, but still depends on the deployment being retained and its runtime being available.