All examples use your own API host and a Bearer API key. Use an Edit key for permitted mutations. Deployment and infrastructure operations require administrative grants. Personal keys remain bounded by the owner’s current team role; team keys retain their explicit service grants.
Deploy an app
List /apps to find an app UUID, then request a deployment:
Set ACTION_ID to a unique value for this intended deployment. The response includes a deployment and whether the request was replayed. Poll GET /deployments/{deploymentId} and GET /deployments/{deploymentId}/steps. Fetch incremental logs with GET /deployments/{deploymentId}/logs?after=42; use the last returned sequence in the next call.
Terminal deployment states are succeeded, succeeded_with_warnings, failed, cancelled, and skipped. Do not treat 202, a queued state, or an HTTP success as a successful deployment.
To stream deployment updates:
Each deployment event contains the deployment, logs, and steps. Streams end after a terminal state or a bounded polling period. Reconnect with Last-Event-ID from the last event, or after containing the last log sequence. Use ?snapshot=true for one finite snapshot; MCP always uses this mode.
Roll back or cancel
Read /apps/{appId}/releases, then POST /apps/{appId}/actions/rollback with an Idempotency-Key and body {"releaseId":"RELEASE_UUID"}. An empty object selects the previous release when available. Resource rollback follows the corresponding /resources route.
POST /deployments/{deploymentId}/actions/cancel requests cancellation. Poll the deployment to see the final result. A retry uses /deployments/{deploymentId}/actions/retry and a fresh idempotency key for the new attempt.
Reconcile a repository
Optionally discover declared environments with POST /sources/discover, using repository details from /github/repositories and the repository default branch as discoveryBranch. Discovery is only a suggestion step; connection does not require it. Connect the repository with POST /sources/connect, mapping each selected environment to its branch. Initial sync imports configuration without deploying. For later reconciliation, call POST /sources/{sourceId}/environments/{environmentId}/syncs, or /sources/{sourceId}/environments/syncs for all connected environments. These explicit syncs import configuration without deploying. Mapped-branch push events can queue opted-in deployments. Inspect each queue outcome and read /sources/{sourceId}/syncs/{syncId} for completion and validation errors.
Automatic deployment controls can be read or changed at /sources/{sourceId}/auto-deploy-control, /apps/{appId}/auto-deploy-control, and /resources/{resourceId}/auto-deploy-control. Repository-level and workload-level controls combine as they do in the UI.
Update secrets safely
Read /settings/secrets for workspace bindings and their revisions. Repository, app, and resource secret routes use the same model. Reads expose names and revision metadata, never plaintext values.
The local secret-change.json contains:
Use null only when creating a previously empty secret slot. For an existing slot, send its current revision UUID. A stale revision returns 409; read the latest metadata and reconcile changes. A request changes 1–200 keys, and cannot set and delete the same key. Keep real secret files outside source control.
Workspace values use the production storage path and are shared across environments when explicitly referenced. For repository and workload values, use the connected environment name, such as production or staging. Preview scopes use preview:<environment>, such as preview:staging. Stages are build, deployment, pre_deploy, and post_deploy. Server Cloudflare tokens use /servers/{serverId}/credentials. Select an existing stored SSH key with /servers/{serverId}/credentials/actions/verify-private-key, passing privateKeyId and expectedRevision. Creating or revealing private keys requires the Admin dashboard.
Servers, backups, and previews
Create a server with POST /servers, select its stored SSH key for verification, compare a discovered host-key fingerprint independently, and trust the matching key. Use /servers/{serverId}/actions/prepare and follow /preparations until ready. /actions/check refreshes runtime health and capacity; inspect /checks for the outcome.
For resource backups, use /resources/{resourceId}/actions/backup. Read /operations and /backup-assurance. Restore and cleanup operations have explicit request schemas and state constraints in the reference. Restores can overwrite database contents; inspect the backup, target, and required confirmation fields before invoking them.
Preview deployment and cleanup use /previews/{previewEnvironmentId}/actions/deploy and /actions/delete. Preview inventories are available under the parent app or source. Cleanup is asynchronous and must be checked for failures. Last modified on September 5, 2026
