Pular para o conteúdo principal
A API da Cube segue o estilo REST: rotas previsíveis, respostas em JSON e os códigos HTTP de sempre. É a mesma API que o painel usa, com uma chave no lugar do login.

URL base

Todo pedido vai por HTTPS.

Autenticação

Mande a sua chave de API no cabeçalho Authorization:
1

Crie a chave

No painel, abra Chaves de API e clique para criar. Dê um nome (como “CI do GitHub”), marque as permissões (ou escolha um modelo, como Deploy (CI/CD)) e confirme com a sua senha.
2

Copie na hora

A chave começa com cube_ e aparece uma vez só. Guarde num gerenciador de segredos ou numa variável de ambiente, como CUBE_API_KEY.
3

Use

Mande Authorization: Bearer $CUBE_API_KEY em todo pedido. Sem cookie e sem nada mais.
Cada chave tem só as permissões que você marcar, caixa por caixa (como projects:read, projects:deploy ou files:write), com modelos prontos: Leitura, Ler e escrever, Deploy (CI/CD), Só Blob (a chave para o código do seu projeto) e Tudo. Cada rota pede uma permissão; sem ela, a resposta é 403 insufficient_scope com a que falta em requiredScope. A lista completa, com o que cada uma permite, está em Chaves de API.
  • Até 10 chaves por conta. A lista mostra o começo de cada chave e quando ela foi usada pela última vez.
  • Revogar vale no pedido seguinte. Logs abertos com a chave revogada fecham em até 20 segundos.
  • Redefinir a senha ou usar o Não fui eu revoga todas as chaves da conta.
  • Tudo o que a chave faz entra na Atividade com o nome dela.
A chave dá acesso aos seus projetos. Nunca coloque no código, num repositório ou num app que roda no navegador. Vazou? Revogue no painel e crie outra.

O que a chave pode fazer

O MCP da sua conta usa a mesma chave, com as mesmas permissões e o mesmo limite, para o Claude Code, o Cursor e outros agentes. Excluir um backup ou uma versão, ligar o backup automático, os avisos, ver o uso por projeto e cuidar da conta, da cobrança, da equipe, das chaves e de Cube AI são só pelo painel, com permissão nenhuma. Com uma chave, essas rotas respondem 403 api_key_not_allowed ou 401 not_authenticated. Uma chave nunca cria, edita nem revoga outra chave. Numa equipe, a chave criada na área de trabalho da equipe age na equipe (os projetos, o plano e o limite dela), com as permissões da chave, que nunca passam do papel de quem a criou (conferido a cada pedido). Ela é criada e revogada por Admins e pelo dono e para de funcionar quando quem a criou sai ou é removido da equipe.

Limites

Os pedidos com chave contam por conta (todas as chaves somadas), por minuto e por dia: Toda resposta a um pedido com chave válida traz os cabeçalhos do limite: Passou do limite: 429 rate_limit_exceeded com Retry-After. Além disso, as ações pesadas têm limite próprio: um envio de .zip a cada 3 segundos por conta e uma abertura de logs a cada 5 segundos por projeto, com até 5 abertas ao mesmo tempo (429 too_many_requests).

Formato

  • Pedidos com corpo usam JSON (Content-Type: application/json), menos o envio do .zip, que é multipart/form-data.
  • Respostas são JSON com o recurso pelo nome: { "project": { … } } ou { "projects": [ … ] }. Os logs chegam por streaming (text/event-stream).
  • IDs de projeto têm 26 caracteres, como 01J8Z3W6N0Q4Y7V2K5T9D1H3XA.
  • Datas em ISO 8601, em UTC: 2026-09-26T18:00:00.000Z.
  • Memória sempre em MB (memoryMb). 1 GB = 1024 MB.
  • Erros no formato { "status": "error", "code", "message" }. Veja todos em Códigos de erro.

O ciclo de vida de um projeto

Em creating e installing, iniciar, parar e reiniciar respondem 409 project_busy. Nada sobe sem você pedir: um projeto novo só inicia com start=true no envio.

Primeiro pedido

Os exemplos de Node.js usam fetch nativo e await fora de função: rode no Node.js 20 ou mais novo, com o arquivo salvo como .mjs (ou com "type": "module" no package.json). Os de Python usam requests.

Deploy pelo CI

Com uma chave do modelo Deploy (CI/CD) guardada como segredo do CI, um passo basta para atualizar o projeto a cada push:
O projeto volta ao ar com o código novo sozinho, se estava ligado. Veja Enviar novo código.