Fazer rollback da aplicação para uma release

curl --request POST \
  --url https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "restore_environment": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', '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));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"

payload = { "restore_environment": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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("Authorization", "Bearer <token>")
	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))

}

{
  "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"
  }
}

POST

apps

{id}

releases

{release_id}

rollback

Fazer rollback da aplicação para uma release

curl --request POST \
  --url https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "restore_environment": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', '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));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/releases/{release_id}/rollback"

payload = { "restore_environment": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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("Authorization", "Bearer <token>")
	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))

}

{
  "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"
  }
}

Faz o rollback da aplicação para o código que ela tinha nesta release, depois a reinicia. O rollback é registrado como uma nova release com source: "rollback", então você pode desfazê-lo do mesmo jeito. Opcionalmente, ele também restaura as variáveis de ambiente salvas com essa release. Fazer rollback não altera os dados que a aplicação criou enquanto roda, como um arquivo de banco de dados ou uploads. Para trazer os dados de volta, use um snapshot.

string

obrigatório

O ID da aplicação. Se a aplicação pertencer a um workspace, informe o ID dele no query parameter workspace_id.

string

obrigatório

O ID da release para a qual fazer o rollback, como retornado pela lista de releases. Precisa ser uma release cujo código ainda é mantido (rollback.available é true).

string

Se a aplicação pertencer a um workspace, o ID do workspace.

boolean

padrão:"false"

Opcional. true também substitui as variáveis de ambiente da aplicação pelas salvas com essa release. O padrão false mantém as variáveis que a aplicação tem agora. Confira antes as mudanças com a pré-visualização do rollback.

O que o rollback faz:

Código: cada arquivo de código da release é restaurado exatamente como estava. Arquivos de código que a release não tinha são apagados.
Dados: arquivos criados pela aplicação enquanto roda não são alterados nem apagados.
Variáveis: não mudam, a menos que restore_environment seja true.
Restart: a aplicação reinicia com um build forçado, então o comando de build dela roda de novo, se tiver um.
Histórico de releases: a versão que estava rodando passa para rolled_back, e a nova release passa a ser a ativa. O rollback.from dela é a release que você restaurou.

Outras regras se aplicam:

Um rollback não usa os slots de deploy do seu plano, mas dois rollbacks da mesma aplicação precisam de pelo menos 30 segundos entre eles. Rollbacks também têm limite horário próprio por conta, igual ao limite horário de deploy do seu plano. Ao ultrapassá-lo, a resposta é 429 DEPLOY_RATE_LIMITED, com details.limit, details.window_seconds e details.retry_after, e nenhum slot de deploy é usado.
Se o código da release não puder ser restaurado, a requisição falha com INTERNAL_SERVER_ERROR. Nada muda. Se o código salvo dessa release estiver danificado, falha com INVALID_ZIP_STRUCTURE (400) antes de qualquer arquivo ser tocado.
Se o restart falhar depois que os arquivos foram restaurados, a resposta é o erro do restart (por exemplo BUILD_FAILED). A aplicação já roda o código restaurado, então corrija a causa e reinicie-a.

Só as releases que o seu plano mantém podem ser restauradas. Veja Histórico de deploys e limites de rollback. Exige o escopo apps:write quando chamado com uma chave de API. Se restore_environment for true, a chave também precisa do escopo apps:envs; sem ele, a requisição retorna 403 API_KEY_SCOPE_DENIED. Para um membro do workspace, exige as permissões apps:files e apps:lifecycle, além de apps:envs ao restaurar variáveis.

Resposta

object

A nova release criada pelo rollback.

Mostrar Mostrar objeto

string

O ID da nova release.

string

Sempre rollback nesta resposta.

string

active, a versão que a aplicação roda agora.

object

Mostrar Mostrar objeto

boolean

false para a release ativa.

string

O ID da release que foi restaurada.

string | null

A mensagem da release. null quando nenhuma foi informada.

integer

Número de arquivos alterados pela operação que gerou esta release.

integer | null

Tempo, em milissegundos, gasto no build e na inicialização da aplicação.

string | null

Quando a aplicação iniciou pela primeira vez com o código desta release, ou seja, quando o restart do rollback terminou.

string

Timestamp ISO de quando o rollback foi feito.

string

O nome do usuário que fez o rollback.

string

O ID da aplicação.

null

null, porque um rollback não é um push do GitHub.

boolean

true quando um log de crash foi registrado para esta 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"
  }
}

Respostas de erro

string

Códigos de erro possíveis:

AUTH_TOKEN_MISSING, API_KEY_INVALID, SESSION_REVOKED: o header Authorization está ausente, a chave de API é inválida ou a sessão do painel foi revogada (401).
API_KEY_IP_DENIED: a chave de API é usada a partir de um IP fora da sua allowlist (403).
APP_NOT_FOUND: a aplicação não existe, ou não pertence a esta conta ou workspace (404).
RELEASE_NOT_FOUND: a release não existe, ou pertence a outra aplicação (404).
PLAN_DOES_NOT_SUPPORT_ROLLBACK: o seu plano não inclui fazer rollback para releases anteriores (403). O rollback começa no Pro.
API_KEY_SCOPE_DENIED: a chave de API não tem o escopo apps:write, ou não tem apps:envs enquanto restore_environment é true (403).
RELEASE_ALREADY_ACTIVE: a release já é a que a aplicação roda, ou tem o mesmo código e restore_environment não mudaria nada (409).
RELEASE_EXPIRED: o código desta release não é mais mantido, porque expirou ou é mais antigo do que o número de releases que o seu plano mantém (410).
OPERATION_IN_PROGRESS: outra operação de ciclo de vida na mesma aplicação já está em execução (409). Nada foi alterado; aguarde alguns segundos e tente de novo.
RESTORE_COOLDOWN: o rollback anterior desta aplicação foi há menos de 30 segundos (429). Aguarde e tente de novo.
DEPLOY_RATE_LIMITED: o limite horário de rollbacks da conta foi atingido (429). details traz limit, window_seconds e retry_after. Aguarde e tente de novo.

string

Uma mensagem descritiva com detalhes adicionais sobre o erro.

{
  "code": "RELEASE_EXPIRED"
}

{
  "code": "RESTORE_COOLDOWN"
}

Última modificação em 28 de outubro de 2026

Visão geral

Endpoints

Fazer rollback da aplicação para uma release

Resposta

Respostas de erro

​Resposta

​Respostas de erro

Resposta

Respostas de erro