Roll Back Application to a Release
curl --request POST \
--url https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback \
--header 'Content-Type: application/json' \
--data '
{
"restore_environment": true
}
'import requests
url = "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"
payload = { "restore_environment": True }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({restore_environment: true})
};
fetch('https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'restore_environment' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"
payload := strings.NewReader("{\n \"restore_environment\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback")
.header("Content-Type", "application/json")
.body("{\n \"restore_environment\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"restore_environment\": true\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "5b8e3f10-2c4a-4d9b-a7e1-0f3c6b9d2e54",
"app_id": "7a52e0d4-19b3-4f8e-b6c2-0d9e4a1f5c73",
"source": "rollback",
"status": "active",
"message": null,
"author": "octocat",
"github": null,
"files_changed": 4,
"rollback": {
"available": false,
"expires_at": null,
"from": "3f1c2a9e-8b7d-4c21-9e0a-5d6f7a8b9c01"
},
"has_log": false,
"build_duration_ms": 12450,
"first_started_at": "2026-10-11T15:02:50.000Z",
"created_at": "2026-10-11T15:02:37.000Z"
}
}
Releases
Roll Back Application to a Release
Rolls an application back to an earlier release, restoring its code, removing files it did not have and restarting it, with optional variables.
POST
/
v1
/
apps
/
{id}
/
releases
/
{release_id}
/
rollback
Roll Back Application to a Release
curl --request POST \
--url https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback \
--header 'Content-Type: application/json' \
--data '
{
"restore_environment": true
}
'import requests
url = "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"
payload = { "restore_environment": True }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({restore_environment: true})
};
fetch('https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'restore_environment' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"
payload := strings.NewReader("{\n \"restore_environment\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback")
.header("Content-Type", "application/json")
.body("{\n \"restore_environment\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"restore_environment\": true\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "5b8e3f10-2c4a-4d9b-a7e1-0f3c6b9d2e54",
"app_id": "7a52e0d4-19b3-4f8e-b6c2-0d9e4a1f5c73",
"source": "rollback",
"status": "active",
"message": null,
"author": "octocat",
"github": null,
"files_changed": 4,
"rollback": {
"available": false,
"expires_at": null,
"from": "3f1c2a9e-8b7d-4c21-9e0a-5d6f7a8b9c01"
},
"has_log": false,
"build_duration_ms": 12450,
"first_started_at": "2026-10-11T15:02:50.000Z",
"created_at": "2026-10-11T15:02:37.000Z"
}
}
Rolls the application back to the code it had in this release, then restarts it. The rollback is recorded as a new release with
What the rollback does:
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.- 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_environmentistrue. - 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. Itsrollback.fromis the release you restored.
- 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, withdetails.limit,details.window_secondsanddetails.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.
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.
Show Toggle object
Show Toggle object
string
The ID of the new release.
string
Always
rollback for this response.string
active, the version the application runs now.object
string | null
The release message.
null when none was given.integer
Number of files changed by the operation that produced this release.
integer | null
Time, in milliseconds, spent building and starting the application.
string | null
When the application first started with this release’s code, that is, when the rollback restart finished.
string
ISO timestamp of when the rollback was made.
string
The name of the user who made the rollback.
string
The ID of the application.
null
null, because a rollback is not a GitHub push.boolean
true when a crash log was recorded for this release.{
"response": {
"id": "5b8e3f10-2c4a-4d9b-a7e1-0f3c6b9d2e54",
"app_id": "7a52e0d4-19b3-4f8e-b6c2-0d9e4a1f5c73",
"source": "rollback",
"status": "active",
"message": null,
"author": "octocat",
"github": null,
"files_changed": 4,
"rollback": {
"available": false,
"expires_at": null,
"from": "3f1c2a9e-8b7d-4c21-9e0a-5d6f7a8b9c01"
},
"has_log": false,
"build_duration_ms": 12450,
"first_started_at": "2026-10-11T15:02:50.000Z",
"created_at": "2026-10-11T15:02:37.000Z"
}
}
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 theapps:writescope, or it lacksapps:envswhilerestore_environmentistrue(403).RELEASE_ALREADY_ACTIVE: The release is already the one the application runs, or it has the same code andrestore_environmentwould 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).detailscarrieslimit,window_secondsandretry_after. Wait and retry.
string
A descriptive message providing additional details about the error.
{
"code": "RELEASE_EXPIRED"
}
{
"code": "RESTORE_COOLDOWN"
}