URL base
Autenticação
Mande a sua chave de API no cabeçalhoAuthorization:
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.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.
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
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.

