> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Voltar para a versão
> Troca os arquivos do projeto pelos de uma versão guardada. Só liga depois se você pedir.
O projeto para antes, os arquivos voltam aos do `.zip` daquela versão e as dependências só são instaladas de novo se o manifesto mudou, como no [Enviar novo código](/api-reference/projects/upload-code). Sem `shouldStart`, o projeto fica **parado** até você iniciar. O histórico ganha uma linha `rollback` com `restoredFrom`, e a Atividade registra quem voltou.
Deploy que quebrou no CI? Pegue a versão anterior no [Histórico de envios](/api-reference/deployments/list) (a segunda com `isRestorable`) e volte para ela com `shouldStart: true`.
## Erros comuns
| Código | HTTP | O que fazer |
| -------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------- |
| [`deployment_not_available`](/errors#param-deployment-not-available) | 409 | A versão saiu do histórico guardado: escolha uma com `isRestorable`. |
| [`project_busy`](/errors#param-project-busy) | 409 | Espere a instalação atual terminar. |
| [`plan_limit_reached`](/errors#param-plan-limit-reached) | 422 | Com `shouldStart`, o projeto não cabe no plano ligado: pare outro ou volte sem iniciar. |
| [`too_many_requests`](/errors#param-too-many-requests) | 429 | Um envio a cada 3 s por conta: espere o `Retry-After`. |
| [`server_unavailable`](/errors#param-server-unavailable) | 503 | O projeto ficou parado: confira os arquivos antes de iniciar. |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml POST /projects/{id}/deployments/{deploymentId}/rollback
openapi: 3.1.0
info:
title: API da Cube Hosting
version: 1.0.0
description: >-
Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
inicie, pare, reinicie, leia logs e métricas, cuide das variáveis de
ambiente, faça e baixe backups, volte para uma versão anterior e veja o uso
do plano. Para agentes de IA, o servidor MCP da conta (`POST
https://app.cubehosting.com.br/api/mcp`, JSON-RPC, com a mesma chave) está
em https://docs.cubehosting.com.br/account-mcp.
contact:
name: Cube Hosting
url: https://discord.gg/pv6D9tUsDV
servers:
- url: https://app.cubehosting.com.br/api
security:
- bearerAuth: []
tags:
- name: Projetos
- name: Controle
- name: Logs e métricas
- name: Variáveis de ambiente
- name: Backups
- name: Versões dos envios
- name: Avisos
- name: Conta
paths:
/projects/{id}/deployments/{deploymentId}/rollback:
post:
tags:
- Versões dos envios
summary: Voltar para a versão
description: >-
Troca os arquivos do projeto pelos do `.zip` daquela versão, pelo mesmo
caminho de [Enviar novo código](/api-reference/projects/upload-code): o
projeto **para antes**, os arquivos são trocados, as dependências só são
instaladas de novo se o `package.json` ou o `requirements.txt` mudou, e
a configuração (comando, memória, variáveis) continua a de agora. O
projeto termina **parado**, a não ser com `shouldStart: true`, que liga
depois da instalação (se ele couber no plano, como o
[Iniciar](/api-reference/projects/start)). A resposta chega quando os
arquivos já foram trocados, com o projeto em `installing`; acompanhe
pelos logs de instalação. Guia em [Versões e voltar
atrás](/hosting/versions).
operationId: rollbackDeployment
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/DeploymentId'
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
shouldStart:
type: boolean
default: false
description: >-
`true` liga o projeto quando a instalação terminar. Sem ele,
o projeto fica parado até você iniciar.
example:
shouldStart: true
responses:
'202':
description: Os arquivos voltaram aos da versão, e a instalação começou.
content:
application/json:
schema:
$ref: '#/components/schemas/InstallStarted'
example:
project:
id: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
name: Meu bot
description: Atende o servidor da loja
type: bot
language: node
version: '24'
entry: index.js
command: node index.js
memoryMb: 256
port: null
subdomain: null
url: null
status: installing
error: null
hasAutoRestart: true
consecutiveCrashes: 0
lastExit: null
usage: null
startedAt: null
createdAt: '2026-09-26T18:00:00.000Z'
updatedAt: '2026-09-26T18:01:10.000Z'
isReinstallingDependencies: false
'400':
description: O corpo está fora do formato.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: invalid_request
value:
status: error
code: invalid_request
message: >-
Envie { "shouldStart": true } para iniciar depois, ou
false (o padrão).
'401':
description: Chave ausente, inválida ou revogada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_api_key:
summary: invalid_api_key
value:
status: error
code: invalid_api_key
message: >-
Chave de API inválida ou revogada. Confira o cabeçalho
"Authorization: Bearer " ou crie outra em Chaves de
API no painel.
'403':
description: >-
A chave é só de leitura, ou (com `shouldStart`) o plano não inclui
sites.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_permission:
summary: insufficient_permission
value:
status: error
code: insufficient_permission
message: >-
Esta chave é só de leitura. Para enviar, iniciar, parar,
reiniciar, mexer nas variáveis, fazer e baixar backups ou
baixar e voltar versões dos envios, crie uma chave de
leitura e escrita no painel.
site_not_allowed:
summary: site_not_allowed
value:
status: error
code: site_not_allowed
message: >-
O plano Free não inclui sites. Mude para um plano pago
para colocar este site no ar.
'404':
description: O projeto ou a versão não existe ou não é da sua conta.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
summary: not_found
value:
status: error
code: not_found
message: Versão não encontrada.
'409':
description: >-
A versão não está mais guardada, o projeto está instalando ou com
outra ação, ou a conta está suspensa. Nada mudou.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
deployment_not_available:
summary: deployment_not_available
value:
status: error
code: deployment_not_available
message: >-
Esta versão não está guardada. Só os envios de .zip dos
últimos 30 dias, até o limite do seu plano, podem ser
baixados ou restaurados.
project_busy:
summary: project_busy
value:
status: error
code: project_busy
message: >-
O projeto está sendo preparado ou já tem outra ação em
andamento. Espere terminar.
account_suspended:
summary: account_suspended
value:
status: error
code: account_suspended
message: >-
Sua conta está suspensa porque o Pix da renovação não foi
pago, então os projetos ficam parados. Pague em Plano e
cobrança: a conta volta na hora, e o que estava no ar sobe
sozinho.
beta_ending:
summary: beta_ending
value:
status: error
code: beta_ending
message: >-
Seu beta terminou e a conta está voltando ao plano Free.
Espere alguns minutos e tente de novo.
'422':
description: >-
O `.zip` foi recusado na troca, ou (com `shouldStart`) o projeto não
cabe no plano ligado. Os arquivos e o projeto ficaram como estavam.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unsafe_zip:
summary: unsafe_zip
value:
status: error
code: unsafe_zip
message: >-
Descompactado, o projeto passa do limite de 500 MB. Tire
os arquivos grandes que o bot não usa e envie de novo.
reason: size
plan_limit_reached:
summary: plan_limit_reached
value:
status: error
code: plan_limit_reached
message: >-
Este projeto usa 512 MB, mas o plano Block só tem 256 MB
livres com os projetos que estão ligados. Diminua a
memória dele em Configurações ou pare outro projeto.
freeMemoryMb: 256
requestedMemoryMb: 512
'429':
description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limit_exceeded:
summary: rate_limit_exceeded
value:
status: error
code: rate_limit_exceeded
message: >-
A sua conta passou do limite da API do plano Free: 10
pedidos por minuto. Espere 42 s e tente de novo.
too_many_requests:
summary: too_many_requests
value:
status: error
code: too_many_requests
message: >-
Muitas requisições seguidas. Espere alguns segundos e
tente de novo.
too_many_attempts:
summary: too_many_attempts
value:
status: error
code: too_many_attempts
message: Muitas tentativas. Tente de novo em 15 minutos.
'503':
description: >-
O armazenamento das versões não respondeu (nada mudou), ou o
servidor dos projetos não respondeu no meio da troca: aí o projeto
fica parado e a mensagem diz isso.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
deployments_unavailable:
summary: deployments_unavailable
value:
status: error
code: deployments_unavailable
message: >-
As versões guardadas não estão disponíveis agora. Tente de
novo em instantes.
server_unavailable:
summary: server_unavailable
value:
status: error
code: server_unavailable
message: >-
O servidor dos projetos não respondeu no meio da troca de
versão. O projeto ficou parado: confira os arquivos antes
de iniciar ou tente de novo em instantes.
x-codeSamples:
- lang: bash
label: curl
source: >-
curl -X POST
https://app.cubehosting.com.br/api/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/rollback
\
-H "Authorization: Bearer $CUBE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"shouldStart": true}'
- lang: javascript
label: Node.js
source: >-
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const res = await fetch(
`${API}/projects/${process.env.PROJECT_ID}/deployments/${process.env.DEPLOYMENT_ID}/rollback`,
{
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ shouldStart: true }),
},
);
const { project, isReinstallingDependencies } = await res.json();
console.log(project.status, isReinstallingDependencies); //
installing
- lang: python
label: Python
source: |-
import os
import requests
API = "https://app.cubehosting.com.br/api"
headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}
r = requests.post(
f"{API}/projects/{os.environ['PROJECT_ID']}/deployments/{os.environ['DEPLOYMENT_ID']}/rollback",
headers=headers,
json={"shouldStart": True},
timeout=300,
)
r.raise_for_status()
print(r.json()["project"]["status"])
components:
parameters:
ProjectId:
name: id
in: path
required: true
description: >-
O ID do projeto (26 caracteres). Aparece no painel, no topo do projeto,
e em `GET /projects`.
schema:
type: string
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
example: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
DeploymentId:
name: deploymentId
in: path
required: true
description: >-
O ID da versão (UUID), do [Histórico de
envios](/api-reference/deployments/list).
schema:
type: string
format: uuid
example: 3f2b8c1e-6a4d-4e7b-9c2a-1d5e8f0a7b36
schemas:
InstallStarted:
type: object
required:
- project
- isReinstallingDependencies
properties:
project:
$ref: '#/components/schemas/Project'
isReinstallingDependencies:
type: boolean
description: >-
`true` quando as dependências vão ser instaladas de novo; `false`
quando só o build (se houver) roda.
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: string
const: error
code:
type: string
description: Código fixo em inglês. Veja [Códigos de erro](/errors).
message:
type: string
description: Texto em português para mostrar a uma pessoa.
additionalProperties: true
Project:
type: object
description: 'Um projeto: um bot ou um site.'
required:
- id
- name
- description
- type
- language
- version
- entry
- command
- memoryMb
- port
- subdomain
- url
- status
- error
- hasAutoRestart
- consecutiveCrashes
- lastExit
- usage
- startedAt
- createdAt
- updatedAt
properties:
id:
type: string
description: ID do projeto, 26 caracteres.
name:
type: string
maxLength: 40
description: Nome do projeto.
description:
type: string
maxLength: 200
description: Descrição do painel. `""` quando não tem.
type:
type: string
enum:
- bot
- site
language:
type: string
enum:
- node
- python
version:
type: string
description: '`20`, `22` ou `24` (Node.js); `3.11` ou `3.12` (Python).'
entry:
type:
- string
- 'null'
description: >-
Arquivo principal: o arquivo que o comando roda, relativo à raiz do
projeto (como `index.js` ou `src/bot.py`). Vem do `command` quando
ele é só `node ` ou `python `, e muda em
Configurações › Geral. `null` com um comando próprio, como `npm
start`.
command:
type: string
description: >-
Comando de início, o que de fato roda. Quando é `node ` ou
`python `, o painel mostra o campo vazio (vazio = roda o
arquivo principal).
memoryMb:
type: integer
description: Memória reservada, em MB. É também o teto do processo.
port:
type:
- integer
- 'null'
description: >-
Só site: a porta em que o app escuta (também na variável `PORT`).
`null` em bot.
subdomain:
type:
- string
- 'null'
description: 'Só site: o nome em `nome.cubehost.dev`. `null` em bot.'
url:
type:
- string
- 'null'
format: uri
description: 'Só site: o endereço público com HTTPS. `null` em bot.'
status:
$ref: '#/components/schemas/ProjectStatus'
error:
oneOf:
- $ref: '#/components/schemas/ProjectError'
- type: 'null'
description: O motivo, quando `status` é `error` ou `crash_loop`.
hasAutoRestart:
type: boolean
description: '`true` nos planos pagos: o projeto volta sozinho se cair.'
consecutiveCrashes:
type: integer
description: >-
Quedas seguidas desde a última vez que rodou 60 segundos sem cair.
Com 5, o projeto vai para `crash_loop`.
lastExit:
oneOf:
- $ref: '#/components/schemas/LastExit'
- type: 'null'
description: A última vez que o processo terminou.
usage:
oneOf:
- $ref: '#/components/schemas/Usage'
- type: 'null'
description: O uso de agora. Só com `status` `running`.
startedAt:
type:
- string
- 'null'
format: date-time
description: >-
Quando o processo subiu (o "tempo no ar" do painel). Só com
`running`.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ProjectStatus:
type: string
enum:
- creating
- installing
- running
- stopped
- restarting
- crash_loop
- error
description: >-
`creating` (Enviando), `installing` (Instalando), `running` (No ar),
`stopped` (Parado), `restarting` (Reiniciando), `crash_loop` (Em loop de
erro), `error` (Com erro).
ProjectError:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- install_failed
- install_timeout
- install_out_of_memory
- install_interrupted
- start_failed
- process_exited
- crash_loop
description: >-
Veja [Estados de erro do
projeto](/errors#estados-de-erro-do-projeto).
message:
type: string
description: Explicação em português.
LastExit:
type: object
required:
- code
- isOutOfMemory
- exitedAt
properties:
code:
type: integer
description: O código de saída do processo.
isOutOfMemory:
type: boolean
description: '`true` se o processo passou da memória do projeto.'
exitedAt:
type: string
format: date-time
Usage:
type: object
required:
- memoryMb
- cpuPercent
- networkInBps
- networkOutBps
properties:
memoryMb:
type: integer
description: Memória em uso, em MB.
cpuPercent:
type: number
description: Uso de processador. 100 = um núcleo inteiro.
networkInBps:
type: integer
description: Rede recebida, em bytes por segundo.
networkOutBps:
type: integer
description: Rede enviada, em bytes por segundo.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
Mande como `Authorization: Bearer cube_…`.
````