/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Promote Deployment

Promote Deployment

Promote a deployed preview build to production.

POST/v1/projects/{projectId}/deploy/promoteTry it
API key or session token

Put a deployed preview live. Promotion queues a new production build from the preview's uploaded source — the same thing stx deploy --promote does.

Note

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

NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).

Request Body

The body must be JSON. Send {} to promote the most recent deployment.

NameDescription
buildId:stringbody
The preview build to promote. It must belong to this project and have status deployed. 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

Statuserror.codeWhen
400bad_requestThe build is not in the deployed state
401unauthorizedNo credential, or an invalid, revoked or expired one
402USAGE_LIMIT_EXCEEDEDThe workspace has used its monthly build quota. Nothing is created or queued — see Usage limit errors
403forbiddenYou are not a member of the project's workspace, or the API key's scope is below build
404not_foundThe 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

400 Bad Request

json
{
"error": {
"code": "bad_request",
"message": "Build is not in deployed state",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

404 Not Found

json
{
"error": {
"code": "not_found",
"message": "No deployable build found",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/deploy/promote \
-H "Authorization: Bearer stx_abc12345_..." \
-H "Content-Type: application/json" \
-d '{ "buildId": "bld_abc456" }'
Responseapplication/json
202Accepted
{
"data": {
"buildId": "bld_new123",
"status": "queued",
"promotedFrom": "bld_abc456",
"message": "Preview deployment is being promoted to production"
}
}
Responseapplication/json
200OK
{
"data": {
"message": "Build is already in production",
"deployUrl": "https://api-docs-docs.syntext.dev"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext