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

Roll Back Deployment

Put an earlier version of the docs back into production.

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

Put an earlier version of the site back into production. Name either a build that deployed to production, or a commit of the connected repository.

Note

Any workspace member (session JWT), or an API key bound to this project with the build scope or higher. Any plan. Only a rollback that has to rebuild counts toward the monthly build quota — an instant rollback never does, so it works even when the quota is used up.

A rollback is instant when it can be, and falls back to a rebuild when it can't. The response's mode says which happened.

Instant rollback

Every production deploy is stored in full, and the live site points at one of them. Syntext keeps the 5 newest production deploys (plus whichever one is live). When the target build recorded its deploy (deployId on the build) and that deploy is still kept, the rollback just switches the live site back to it, the same way a deploy goes live. Nothing is built.

•
Returns 200 with mode: "instant".
•
Uses no build quota and is never refused for quota.
•
Creates a build row so the rollback shows in the history: trigger: "rollback", status: "deployed", the target's branch, commit, deployUrl, pageCount and deployId, and you as triggeredByUserId (null for an API key). Its log has two lines: what was restored, and a warning that search and the assistant update on the next build.
•
With commitSha, the target is the newest deployed production build of this project whose commit starts with that sha and that recorded its deploy.
Warning

Search and the AI assistant are not rolled back. They are built from your source during a build, and a stored deploy holds only the rendered site. After an instant rollback they keep answering from the newest build's content until the next production build. That build always runs in full — it is never skipped as "unchanged" — and re-indexes everything.

An instant rollback never runs alongside a build. If any build of the project is running (preview and versioned builds included), or a production build created in the last hour is still queued or running, the rollback answers 409 build_in_progress and changes nothing. Cancel that build or wait for it, then retry. A production build requested after a successful rollback deploys after it and replaces it, like any newer deploy.

Rebuild fallback

When the target has no recorded deploy (it predates November 2026, was skipped as unchanged, or — with commitSha — no deployed production build has that commit), or its deploy is no longer kept, the rollback queues a new, forced production build of the target version instead:

•
Returns 202 with mode: "rebuild" and a reason: no_deploy_id or deploy_pruned.
•
Counts toward the monthly build quota, and returns 402 USAGE_LIMIT_EXCEEDED once it is used up. The quota is checked only after the target has been validated.
•
It never skips as "unchanged", and it replaces production only once it deploys, like any other build.

What it builds from:

•
A git build — its commitSha, checked out from the connected repository.
•
A build uploaded with stx deploy — its retained source bundle. Only the newest upload's bundle on each branch is kept, so rolling back to an older upload returns 409 rollback_unavailable. Redeploy that version from the CLI instead.
•
A commit sha — that commit of the connected repository.

The new build's trigger is manual, its triggeredByUserId is you (or null for an API key), and its commitMessage is Roll back to <sha7>: <original subject> — or Roll back to build <id8> for an upload.

Both modes record deployment.rollback in the workspace audit log, with mode, rolledBackFrom, commitSha, and deployId (instant) or reason (rebuild) in its metadata.

Path Parameters

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

Request Body

Send exactly one of buildId or commitSha. Any other key returns 400 validation_error.

NameDescription
buildId:stringbody
A build of this project to restore. It must have status deployed and must not be a preview — to put a preview live, promote it.
commitSha:stringbody
A commit to build, 7–40 hexadecimal characters. Needs a connected repository. A commit that is not in the repository fails the new build with an error starting Commit a1b2c3d was not found in the repository.

Response

Returns 200 OK for an instant rollback and 202 Accepted for a rebuild. Follow a rebuild with Get Build or its log.

NameDescription
data.buildId:string
The new build: the deployed rollback row (instant), or the queued production build (rebuild).
data.status:string
deployed (instant) or queued (rebuild).
data.mode:string
instant or rebuild.
data.reason:string
Rebuild only — why it could not be instant: no_deploy_id (the target never recorded a deploy) or deploy_pruned (it did, but that deploy is no longer kept).
data.rolledBackFrom:string | null
The build whose version was restored. Instant: always set — with commitSha, the build found by that sha. Rebuild: the buildId you sent, or null when you sent commitSha.
data.commitSha:string | null
The restored commit, lowercased. null when the version came from an uploaded source bundle.

Error Responses

Statuserror.codeWhen
400validation_errorBoth or neither of buildId and commitSha, a bad commitSha, an unknown key, or a body that is not JSON
401unauthorizedNo credential, or an invalid, revoked or expired one
402USAGE_LIMIT_EXCEEDEDRebuild only: the workspace has used its monthly build quota
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, or buildId is not a build of this project
409rollback_target_not_deployedThe build never deployed. details.status is its status
409rollback_target_is_previewThe build is a preview. Promote it instead
409rollback_unavailableRebuild only: there is nothing to rebuild from — see below
409build_in_progressInstant only: a build of this project is running, or a production build is queued. Nothing changed — cancel it or wait, then retry
502rollback_failedInstant only: the rollback could not be completed. The site still serves what it served before — retry

400 Bad Request

json
{
"error": {
"code": "validation_error",
"message": "Send exactly one of buildId or commitSha",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

Field errors, such as a bad commitSha, are listed under details by field name.

409 Conflict — rollback_target_not_deployed

json
{
"error": {
"code": "rollback_target_not_deployed",
"message": "Only a build that deployed can be rolled back to.",
"details": {
"status": "failed",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

409 Conflict — rollback_target_is_preview

json
{
"error": {
"code": "rollback_target_is_preview",
"message": "This is a preview build. Promote it instead of rolling back to it.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

409 Conflict — rollback_unavailable

Returned when the target cannot be rebuilt:

•
With buildId: the build was uploaded from the CLI and its source bundle is no longer kept, or it is a git build with no recorded commit, or the project no longer has a repository connected.
•
With commitSha: the project has no repository connected.
json
{
"error": {
"code": "rollback_unavailable",
"message": "This build cannot be rebuilt: it has no commit to check out and its uploaded source is no longer kept. Redeploy from the CLI or push a revert.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

With commitSha and no repository, the message is No repository is connected, so there is no commit to roll back to.

409 Conflict — build_in_progress

When a production build is queued or running, details names it. When only another kind of build holds the project (a preview or versioned build, or another rollback), there is no buildId in details.

json
{
"error": {
"code": "build_in_progress",
"message": "A production build of this project is queued or running, and it would replace the rollback when it deploys. Cancel it or wait for it to finish, then roll back.",
"details": {
"buildId": "bld_def012",
"status": "compiling",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

502 Bad Gateway — rollback_failed

If switching the live site failed, the rollback's build is marked failed with error: "Rollback failed: …", and details.buildId names it.

json
{
"error": {
"code": "rollback_failed",
"message": "Could not move the live site back. It still serves the same deploy as before. Try again.",
"details": {
"buildId": "bld_rbk456",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

402 Payment Required

Rebuild only: the monthly build quota is used up — see Usage limit errors.

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Monthly build limit reached (100/100). Upgrade your plan for more builds.",
"current": 100,
"limit": 100,
"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/rollback \
-H "Authorization: Bearer stx_abc12345_..." \
-H "Content-Type: application/json" \
-d '{ "buildId": "bld_xyz789" }'
Responseapplication/json
200OK (instant
{
"data": {
"buildId": "bld_rbk456",
"status": "deployed",
"rolledBackFrom": "bld_xyz789",
"commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"mode": "instant"
}
}
Responseapplication/json
202Accepted (rebuild
{
"data": {
"buildId": "bld_rbk457",
"status": "queued",
"rolledBackFrom": "bld_xyz789",
"commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"mode": "rebuild",
"reason": "deploy_pruned"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext