Deployment API

Use platform automation tokens for deploy automation from CI, coding agents, and release tools. Endpoint details are generated from the platform API surface in the Platform API reference.

Keys

Use a platform automation token (pk_) for deployment control.

Key type	Purpose	Deployment control
`pk_` platform automation token	Operates Amodal platform resources	Yes
`ak_` agent runtime key	Calls an agent/runtime on behalf of an app	No
Internal service key	Amodal-owned service-to-service calls	Internal only

Create platform automation tokens from organization settings. Token creation and revocation require a signed-in human user session; automation tokens cannot mint or revoke other tokens.

Roles

Role	Use For
`observer`	Read deploy metadata, status, snapshots, and route resolution.
`operator`	CI and release jobs that redeploy, activate, promote, roll back, and start/stop runtimes.
`admin`	Initial setup flows that also create agents, connect GitHub, configure secrets, or manage broader platform state.

Use operator for routine deployment automation. Use admin only when the automation must create or reconfigure platform resources.

Source Model

GitHub is the source of truth for agent files. Push source changes to the connected repo, then call the deployment endpoints to build, inspect, promote, or roll back.

For end-to-end setup from a coding agent, use Build With A Coding Agent.

CI Pattern

Create an operator platform automation token in organization settings.
Store it as AMODAL_PLATFORM_TOKEN in CI.
Push or merge agent source to the connected GitHub branch.
Trigger redeploy from the generated Platform API reference.
Poll deployment and build status from the generated Platform API reference.
Smoke test the persistent agent URL and any immutable deploy URL.
Promote or roll back using the generated Platform API reference.

Release Calls

Use POST /api/deployments/redeploy after pushing source changes to GitHub. Use POST /api/deployments/promote to move a checked deploy from a preview environment to production:

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

Use POST /api/deployments/rollback when production should return to the previous known-good deployment:

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

The generated OpenAPI document at /openapi.json is the source of truth for request bodies and token-kind requirements.

Runtime URLs

Amodal uses two URL shapes:

URL shape	Behavior
`https://agent-slug.amodalapp.com`	Persistent agent URL. Resolves to the currently active deploy.
`https://deploy-id--agent-slug.amodalapp.com`	Immutable deploy URL. Always resolves to that deploy.

The persistent URL behaves like a production alias: activating or rolling back a deploy moves the alias. Immutable deploy URLs remain stable for smoke tests, previews, and debugging.