Roll back and recover

Source history is append-only, so every recovery creates a new version — you can always undo an undo.

Prerequisites

An API key with full_editor access — see Create an API key
A website with version history — see Edit source code

The two recovery tools

Endpoint	What it changes	Use when
`POST /v1/websiteSourceCode/head/restore`	Head only; copies the files of `to` (`published` or a version number) into a new head version.	The draft went wrong, or you want an older version back with a chance to review before publishing.
`POST /v1/websiteSourceCode/published/rollback-version`	Head and published — validates, builds, and re-publishes version `n` immediately.	Production is broken and must change now.

Both require an edit lease token.

Acquire an edit lease

Acquire a lease

curl -X POST 'https://api.cactal.ai/v1/websiteSourceCode/lease/acquire' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "websiteId": "V1StGXR8_Z5jdHi6B-myT" }'

The response { "leaseToken": "...", "headVersion": 9 } also tells you the current head version. GET /v1/websiteSourceCode/summary reports headVersion, publishedVersion, and hasUnpublishedChanges if you need orientation first.

Discard the draft

Restore the head to match the published website. Production does not change.

Restore head to published

curl -X POST 'https://api.cactal.ai/v1/websiteSourceCode/head/restore' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "V1StGXR8_Z5jdHi6B-myT",
    "to": "published",
    "leaseToken": "exampleLeaseToken00000000000000000000000000"
  }'

The response is { "version": 10, "changed": true }, a new head version containing the published files. If head already matched, changed is false. A website that has never published returns 404.

Restore an older version to head

Bring back a known-good version for review by passing a version number as to. This changes only the draft:

Restore version 7 to head

curl -X POST 'https://api.cactal.ai/v1/websiteSourceCode/head/restore' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "V1StGXR8_Z5jdHi6B-myT",
    "to": "7",
    "leaseToken": "exampleLeaseToken00000000000000000000000000"
  }'

to must be an existing version (1 up to the current head); anything higher returns 400 Version does not exist. Review the result on the draft host, then take it live with the normal pipeline: POST /v1/websiteSourceCode/head/check, then POST /v1/websiteSourceCode/head/publish.

Roll back the published website immediately

When production is broken, skip the review loop. Rollback validates version n, builds it, and re-publishes in one call:

Roll back production to version 7

curl -X POST 'https://api.cactal.ai/v1/websiteSourceCode/published/rollback-version' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "V1StGXR8_Z5jdHi6B-myT",
    "version": 7,
    "leaseToken": "exampleLeaseToken00000000000000000000000000"
  }'

Response

{
  "websiteId": "V1StGXR8_Z5jdHi6B-myT",
  "publishedVersion": 11,
  "deployment": { "id": "dep_9f2k", "status": "ready" }
}

Rollback re-runs the full publish gate: the version must pass validation and build. It does not require billing. It also moves head to the rolled-back content, so head and published end up aligned.

Recover from a failed build

A publish that fails validation or build returns a 400 with the failure message, and the deployment records status: "failed". Inspect it:

Check deployment status

curl -X POST 'https://api.cactal.ai/v1/websiteSourceCode/deployment/status' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "websiteId": "V1StGXR8_Z5jdHi6B-myT", "target": "head" }'

Response (truncated)

{
  "websiteId": "V1StGXR8_Z5jdHi6B-myT",
  "sourceVersion": 11,
  "deployment": { "id": "dep_9f2k", "status": "failed", "failureMessage": "Page \"pricing\" failed to compile", "failureKind": "build" }
}

The recovery loop: fix the offending source file, run POST /v1/websiteSourceCode/head/check until it passes, then publish again. POST /v1/websiteSourceCode/deployment/ensure (body { websiteId, target }) re-triggers a build for the head or published version without publishing — useful to confirm a fix builds cleanly. The published website keeps serving its last ready deployment throughout; a failed build never takes production down.

Verify the outcome

List files changed from published to head to confirm the state you expect:

List changed files

curl 'https://api.cactal.ai/v1/websiteSourceCode/changes?websiteId=V1StGXR8_Z5jdHi6B-myT' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

After a rollback or a restore to published you should see "items": [], meaning head and published match. After restoring an older version to head, items lists what will change when you publish. Inspect a selected entry with GET /v1/websiteSourceCode/files/diff?websiteId=...&name=....

Troubleshooting

409 Invalid edit lease

Another editor acquired the lease after you did. Re-acquire the lease and repeat the operation.

409 Website deployment is still building; retry shortly

Rollback found a build in progress for that version. Retry after a short wait; the build is reused once ready.

404 Website has no published version

Restoring to published and comparing against published need at least one publish. Restore to a version number instead on a never-published website.

Next steps

Preview drafts and versions to review a restored head before publishing
Agent-safe publishing to make rollback a planned part of agent workflows

Get started

Core concepts

Guides

Build with agents

Platform

Roll back and recover

Prerequisites

The two recovery tools

Troubleshooting

Next steps

​Prerequisites

​The two recovery tools

​Troubleshooting

​Next steps

Prerequisites

The two recovery tools

Troubleshooting

Next steps