Promote Deployment
Promote a deployed preview build to production.
Put a deployed preview live. Promotion queues a new production build from the preview's uploaded source — the same thing stx deploy --promote does.
Any workspace member (session JWT), or an API key bound to this project with the build scope or higher. Any plan — a promotion queues a production build, so it counts toward the monthly build quota and returns 402 USAGE_LIMIT_EXCEEDED once it is used up. Promoting a build that is already production uses no quota.
The new build has trigger: "cli_upload", branch main, isPreview: false, the commit message Promoted from <branch> (build <id8>), and triggeredByUserId set to you (or null for an API key). It is always forced, so it never skips as "unchanged". The workspace audit log records deployment.promote, with promotedFrom and fromBranch in its metadata.
Promotion rebuilds the preview's retained source bundle, so it is meant for previews deployed with stx deploy --preview. Only the newest upload on each branch keeps its bundle, and a bundle is never removed while a build still uses it — uploading a preview no longer removes production's bundle.
Path Parameters
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Request Body
The body must be JSON. Send {} to promote the most recent deployment.
buildIddeployed. Omit it to use the project's most recently completed deployed build.Response
202 Accepted — a production build was queued. data has buildId (the new build), status: "queued", promotedFrom (the preview build) and message.200 OK — the build was built from main or master, so it is already production. Nothing is queued, no quota is used and nothing is written to the audit log. data has message and deployUrl.A preview never runs head.html or scripts. If the promoted preview has them and you're not a workspace admin or owner (or a full-access API key one of them created), the production build goes out without them and the response carries a top-level warnings entry { "code": "custom_code_not_applied", … } — see Deploys from the CLI.
Error Responses
| Status | error.code | When |
|---|---|---|
| 400 | bad_request | The build is not in the deployed state |
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 402 | USAGE_LIMIT_EXCEEDED | The workspace has used its monthly build quota. Nothing is created or queued — see Usage limit errors |
| 403 | forbidden | You are not a member of the project's workspace, or the API key's scope is below build |
| 404 | not_found | The project does not exist or is deleted, the API key belongs to another project, buildId is not a build of this project, or the project has no deployed build |