Deployment API

The API reference lists every endpoint, the token kinds it accepts, and its request body.

Credentials

Deployment calls take a pk_ automation token. An ak_ agent API key cannot control deployments.

Prefer an agent-bound operator token for routine releases. See Automation Tokens for creation rules.

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.

Build

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

Start a 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"}'

branch defaults to the source's default branch, and environment defaults to production. The response returns deployId and buildId. Poll GET /api/deployments/{deployId} for deployment status and GET /api/builds/{buildId}/status for build progress. Read build logs at GET /api/builds/{buildId}/logs.

Send "reuseBuild": true to share a build of the same commit: when the environment's newest build is that commit and has not failed, or a push is building it, the response returns that deployment with reused: true and starts no other build. Without reuseBuild, every call starts a build.

A completed build and an active deployment are separate states. Check runtime readiness and isActive before you continue. A build for any environment other than production activates when it completes. A production build activates only when automatic production promotion is on; otherwise it stays inactive until you activate it.

Deploy Settings

GET and PUT /api/agents/{agent_id}/deploy-settings read and change the settings that the Deploys page shows:

ci.deploy in amodal.json further limits which pushes build. See CI Rules.

A push builds nothing when the environment's newest build is already the pushed commit and has not failed, or when another push or a reuseBuild redeploy is building it.

Test And Activate

Test the deploy URL before changing production. 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.

POST /api/deployments/{deployId}/activate activates a deploy in its own environment and deactivates the previous one there. It does not copy a preview deploy into production.

Promote Between Environments

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

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"}'

toEnvironment defaults to production. Confirm that the source environment's active deployment is the one you tested. If its runtime bundle is missing or cannot be copied, promotion fails without changing the destination. Promotion activates the destination regardless of autoPromoteProduction.

For GitHub source, a pending or failing amodal/evals commit status blocks promotion with 422 EVAL_GATE_BLOCKED. A missing status does not block it. Pass "force": true to override the check. See Evals.

Roll Back

Pass the deployment ID 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 most recently activated inactive deployment that completed and was live before. If none qualifies, rollback fails without changing the active deployment. Use an explicit ID for a verified release.

Runtime URLs

Activation, promotion, and rollback in production change where the persistent URL points. A deploy URL stays pinned to its deployment while that deployment and its runtime are retained.