> ## 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.
# Criar um projeto
> Envie um .zip e crie um projeto. A Cube instala as dependências e, com start=true, inicia o projeto sozinha.
Envie o `.zip` como `multipart/form-data` no campo `file`. A configuração vem do [`cube.json`](/cube-json) na raiz do `.zip`, ou dos campos do formulário.
A Cube confere o tamanho, extrai o `.zip` e valida a configuração. Se algo estiver errado, nada é criado e a resposta diz o motivo.
O projeto nasce em `installing`. As dependências são instaladas e o build roda, se houver. Acompanhe pelos [logs](/api-reference/projects/logs) com `source=build`.
Com `start=true`, o projeto sobe sozinho (`running`). Sem ele, fica `stopped` até você [iniciar](/api-reference/projects/start).
Guarde tokens em [variáveis de ambiente](/api-reference/projects/set-variables), não no `.zip`. Para um bot que precisa do token para entrar, crie o projeto sem `start`, defina as variáveis e depois inicie.
## OpenAPI
````yaml POST /projects
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 e cuide das variáveis de
ambiente.
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
paths:
/projects:
post:
tags:
- Projetos
summary: Criar um projeto
description: >-
Envia um `.zip` e cria o projeto. A Cube extrai o código, lê a
configuração e começa a instalar as dependências: a resposta chega com o
projeto em `installing`. Acompanhe pelo
[projeto](/api-reference/projects/get) ou pelos
[logs](/api-reference/projects/logs) com `source=build`.
A configuração vem do `cube.json` na raiz do `.zip`. Se o formulário
trouxer `language` e `command`, o formulário vale e o `cube.json` é
ignorado. Um envio a cada 3 segundos por conta.
operationId: createProject
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: >-
O `.zip` com o código. Até 5 MB no Free e 10 MB nos planos
pagos.
start:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: '`true` inicia o projeto assim que a instalação terminar.'
name:
type: string
minLength: 1
maxLength: 40
description: >-
Nome do projeto. Vale se o `cube.json` não tiver `name`; sem
nenhum, vira o nome do arquivo.
type:
type: string
enum:
- bot
- site
description: Mesmo significado da chave do `cube.json`.
language:
type: string
enum:
- node
- python
description: >-
Com `language` e `command`, o formulário vale e o
`cube.json` é ignorado.
version:
type: string
description: '`20`, `22` ou `24` (Node.js); `3.11` ou `3.12` (Python).'
command:
type: string
maxLength: 500
description: Comando de início, numa linha só.
memoryMb:
type: integer
minimum: 100
description: Memória em MB. Mínimo 100 (bot) ou 512 (site).
port:
type: integer
minimum: 1024
maximum: 65535
description: Só site. Padrão 8080.
subdomain:
type: string
description: Só site. Sem ele, a Cube gera um.
build:
type: string
maxLength: 500
description: Comando de build. Ausente = automático; vazio = sem build.
encoding:
file:
contentType: application/zip
responses:
'201':
description: Projeto criado, instalando as dependências.
content:
application/json:
schema:
type: object
required:
- project
properties:
project:
$ref: '#/components/schemas/Project'
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'
'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 o plano não comporta mais este projeto.
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 ou mexer nas variáveis, crie uma chave de
leitura e escrita no painel.
project_limit_reached:
summary: project_limit_reached
value:
status: error
code: project_limit_reached
message: >-
O plano Free permite até 1 bot. Exclua um projeto ou mude
de plano.
limit: 1
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 hospedar sites e APIs.
site_limit_reached:
summary: site_limit_reached
value:
status: error
code: site_limit_reached
message: >-
O plano Block permite até 2 sites. Exclua um site ou mude
de plano.
limit: 2
'409':
description: Conflito com o estado da conta.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
subdomain_taken:
summary: subdomain_taken
value:
status: error
code: subdomain_taken
message: Este subdomínio já é de outro site. Escolha outro.
field: subdomain
no_capacity:
summary: no_capacity
value:
status: error
code: no_capacity
message: >-
Nossos servidores estão cheios agora e não dá para liberar
mais memória. Tente de novo mais tarde: estamos abrindo
mais espaço.
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.
'413':
description: O .zip passou do limite do plano (5 MB no Free, 10 MB nos pagos).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_zip:
summary: invalid_zip
value:
status: error
code: invalid_zip
message: >-
O zip passa do limite de 5 MB do plano Free. Tire as
dependências (elas são instaladas aqui) e arquivos que o
projeto não usa.
limitMb: 5
'422':
description: O .zip ou a configuração foram recusados.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_zip:
summary: invalid_zip
value:
status: error
code: invalid_zip
message: >-
O arquivo não é um zip válido (corrompido, protegido por
senha ou vazio). Gere o zip de novo e envie.
unsafe_zip:
summary: unsafe_zip
value:
status: error
code: unsafe_zip
message: >-
O zip tem atalhos (links) para outros arquivos, e eles não
são aceitos. Troque os atalhos pelos arquivos de verdade e
envie de novo.
reason: link
missing_config:
summary: missing_config
value:
status: error
code: missing_config
message: >-
O zip não tem cube.json. Informe a linguagem e o comando
de início do bot.
invalid_config:
summary: invalid_config
value:
status: error
code: invalid_config
message: >-
O cube.json tem um campo que não existe: "memory". Confira
se não é erro de digitação.
field: memory
unsupported_language:
summary: unsupported_language
value:
status: error
code: unsupported_language
message: >-
Por enquanto aceitamos Node.js (versões 20, 22 e 24) e
Python (3.11 e 3.12).
supported:
node:
- '20'
- '22'
- '24'
python:
- '3.11'
- '3.12'
insufficient_memory:
summary: insufficient_memory
value:
status: error
code: insufficient_memory
message: >-
Este bot pede 512 MB, mas o plano Block só tem 256 MB
livres. Diminua a memória no cube.json, exclua ou reduza
outro projeto, ou mude de plano.
freeMemoryMb: 256
requestedMemoryMb: 512
invalid_subdomain:
summary: invalid_subdomain
value:
status: error
code: invalid_subdomain
message: >-
O subdomínio precisa ter de 3 a 32 caracteres: letras
minúsculas sem acento, números e hífen, começando e
terminando com letra ou número e sem dois hífens seguidos.
field: subdomain
reserved_subdomain:
summary: reserved_subdomain
value:
status: error
code: reserved_subdomain
message: >-
Este subdomínio é reservado ou usa o nome de uma marca ou
órgão conhecido, e foi bloqueado para evitar golpes.
Escolha outro.
field: subdomain
'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 servidor dos projetos não respondeu a tempo. Nada foi alterado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
server_unavailable:
summary: server_unavailable
value:
status: error
code: server_unavailable
message: >-
O servidor dos projetos não respondeu. Tente de novo em
instantes.
x-codeSamples:
- lang: bash
label: curl
source: |-
curl https://app.cubehosting.com.br/api/projects \
-H "Authorization: Bearer $CUBE_API_KEY" \
-F "file=@meu-bot.zip" \
-F "start=true"
- lang: javascript
label: Node.js
source: >-
import { openAsBlob } from 'node:fs';
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const form = new FormData();
form.set('file', await openAsBlob('meu-bot.zip'), 'meu-bot.zip');
form.set('start', 'true');
const res = await fetch(`${API}/projects`, { method: 'POST',
headers, body: form });
const { project } = await res.json();
console.log(project.id, project.status); // 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']}"}
with open("meu-bot.zip", "rb") as zip:
r = requests.post(
f"{API}/projects",
headers=headers,
files={"file": ("meu-bot.zip", zip, "application/zip")},
data={"start": "true"},
timeout=300,
)
r.raise_for_status()
print(r.json()["project"]["id"])
components:
schemas:
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
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
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_…`.
````