Roll Back Deployment
Put an earlier version of the docs back into production.
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.
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.
200 with mode: "instant".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.commitSha, the target is the newest deployed production build of this project whose commit starts with that sha and that recorded its deploy.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:
202 with mode: "rebuild" and a reason: no_deploy_id or deploy_pruned.402 USAGE_LIMIT_EXCEEDED once it is used up. The quota is checked only after the target has been validated.What it builds from:
commitSha, checked out from the connected repository.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.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
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Request Body
Send exactly one of buildId or commitSha. Any other key returns 400 validation_error.
buildIddeployed and must not be a preview — to put a preview live, promote it.commitShaCommit 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.
data.buildIddata.statusdeployed (instant) or queued (rebuild).data.modeinstant or rebuild.data.reasonno_deploy_id (the target never recorded a deploy) or deploy_pruned (it did, but that deploy is no longer kept).data.rolledBackFromcommitSha, the build found by that sha. Rebuild: the buildId you sent, or null when you sent commitSha.data.commitShanull when the version came from an uploaded source bundle.Error Responses
| Status | error.code | When |
|---|---|---|
| 400 | validation_error | Both or neither of buildId and commitSha, a bad commitSha, an unknown key, or a body that is not JSON |
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 402 | USAGE_LIMIT_EXCEEDED | Rebuild only: the workspace has used its monthly build quota |
| 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, or buildId is not a build of this project |
| 409 | rollback_target_not_deployed | The build never deployed. details.status is its status |
| 409 | rollback_target_is_preview | The build is a preview. Promote it instead |
| 409 | rollback_unavailable | Rebuild only: there is nothing to rebuild from — see below |
| 409 | build_in_progress | Instant only: a build of this project is running, or a production build is queued. Nothing changed — cancel it or wait, then retry |
| 502 | rollback_failed | Instant only: the rollback could not be completed. The site still serves what it served before — retry |
400 Bad Request
Field errors, such as a bad commitSha, are listed under details by field name.
409 Conflict — rollback_target_not_deployed
409 Conflict — rollback_target_is_preview
409 Conflict — rollback_unavailable
Returned when the target cannot be rebuilt:
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.commitSha: the project has no repository connected.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.
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.
402 Payment Required
Rebuild only: the monthly build quota is used up — see Usage limit errors.