Skip to main content
POST
Roll Back Application to a Release
Rolls the application back to the code it had in this release, then restarts it. The rollback is recorded as a new release with source: "rollback", so you can undo it the same way. Optionally, it also restores the environment variables saved with that release. Rolling back does not touch the data the application created while running, such as a database file or uploads. To bring data back, use a snapshot.
string
required
The ID of the application. If the application belongs to a workspace, pass its ID in the workspace_id query parameter.
string
required
The ID of the release to roll back to, as returned by the release list. It must be a release whose code is still kept (rollback.available is true).
string
If the application belongs to a workspace, the workspace’s ID.
boolean
default:"false"
Optional. true also replaces the application’s environment variables with the ones saved with that release. The default false keeps the variables the application has now. Check the changes first with the rollback preview.
What the rollback does:
  • Code: every code file of the release is restored exactly as it was. Code files the release did not have are deleted.
  • Data: files the application created while running are not changed or deleted.
  • Variables: unchanged unless restore_environment is true.
  • Restart: the application restarts with a forced build, so its build command runs again if it has one.
  • Release history: the version that was running becomes rolled_back, and the new release becomes the active one. Its rollback.from is the release you restored.
More rules apply:
  • A rollback does not use your plan’s deploy slots, but two rollbacks of the same application need at least 30 seconds between them. Rollbacks also have their own hourly limit per account, equal to your plan’s hourly deploy limit. Going over it returns 429 DEPLOY_RATE_LIMITED, with details.limit, details.window_seconds and details.retry_after, and does not use any deploy slot.
  • If the release’s code cannot be restored, the request fails with INTERNAL_SERVER_ERROR. Nothing changes.
  • If the restart fails after the files were restored, the response is the restart’s error (for example BUILD_FAILED). The application already runs the restored code, so fix the cause and restart it.
Only the releases your plan keeps can be restored. See Deploy history and rollback limits. Requires the apps:write scope when called with an API key. If restore_environment is true, the key also needs the apps:envs scope, and without it the request returns 403 API_KEY_SCOPE_DENIED. For a workspace member, it requires the apps:files and apps:lifecycle permissions, plus apps:envs when restoring variables.

Response

object
The new release created by the rollback.

Error Responses

string
Possible error codes:
  • UNAUTHORIZED: User is not authenticated or lacks permissions.
  • APP_NOT_FOUND: The application does not exist, or it is not owned by this account or workspace (404).
  • RELEASE_NOT_FOUND: The release does not exist, or it belongs to another application (404).
  • PLAN_DOES_NOT_SUPPORT_ROLLBACK: Your plan does not include rolling back to earlier releases (403). Rollback starts on Pro.
  • API_KEY_SCOPE_DENIED: The API key does not have the apps:write scope, or it lacks apps:envs while restore_environment is true (403).
  • RELEASE_ALREADY_ACTIVE: The release is already the one the application runs, or it has the same code and restore_environment would change nothing (409).
  • RELEASE_EXPIRED: The code of this release is no longer kept, because it expired or is older than the number of releases your plan keeps (410).
  • OPERATION_IN_PROGRESS: Another lifecycle operation on the same application is already running (409). Nothing was changed; wait a few seconds and retry.
  • RESTORE_COOLDOWN: The previous rollback of this application was less than 30 seconds ago (429). Wait and retry.
  • DEPLOY_RATE_LIMITED: The account’s hourly rollback limit was reached (429). details carries limit, window_seconds and retry_after. Wait and retry.
string
A descriptive message providing additional details about the error.