API e CLI
Tudo o que o painel faz com projetos, deploys, variáveis, domínios e bancos também pode ser feito por HTTP ou pelo terminal — num script, numa pipeline de CI ou num assistente de IA (veja Conectar IA). As permissões são as mesmas do painel e tudo fica na atividade da organização.
Token
Crie um token em Settings → Acesso por IA e API. Ele age como você: só alcança as suas organizações e só faz o que o seu papel em cada uma permite. Escolha “só ler” quando o uso não precisar alterar nada. Guarde como segredo (no GitHub, em Secrets) e revogue na mesma tela se vazar.
CLI
Precisa do Node 20 ou mais novo. No macOS ou no Linux:
curl -fsSL https://claudo.com.br/cli/install.sh | sh
claudo loginNo Windows, baixe claudo.mjs e rode com node claudo.mjs. Exemplos:
claudo projects
claudo env set loja DATABASE_URL # pede o valor sem mostrar
claudo env pull loja # as de Development em .env.local
claudo env import loja .env # grava as de um .env (tudo ou nada)
claudo deploy loja # publica e acompanha até terminar
claudo image n8n n8nio/n8n:latest # imagem Docker pública no lugar do repositório
claudo logs loja --lines 200
claudo logs loja --search "ERROR" --hours 48 # no histórico guardado
claudo restart loja # reinicia sem build (stop e start também)
claudo domains add loja loja.com.br
claudo db create loja --engine postgresql
claudo statusA organização vai em --org slug (sem ela, vale a pessoal) e --json devolve a resposta crua. Em CI, a variável CLAUDO_TOKEN dispensa o login:
# .github/workflows/deploy.yml (passo)
- run: |
curl -fsSL https://claudo.com.br/cli/claudo.mjs -o claudo.mjs
node claudo.mjs deploy loja --org minha-equipe
env:
CLAUDO_TOKEN: ${{ secrets.CLAUDO_TOKEN }}claudo --help lista todos os comandos. A CLI é um arquivo só, sem dependências, e fala com a mesma API descrita abaixo.
API REST
Endereço base e autenticação:
curl https://claudo.com.br/api/v1/projects \
-H "Authorization: Bearer $CLAUDO_TOKEN"Respostas em JSON: { "message": "…", "data": { … } } quando dá certo e { "error": { "code": "…", "message": "…" } } quando não. Para outra organização, acrescente ?organization=slug. Para CI, crie em Settings um token preso a um projeto: ele só alcança as rotas daquele projeto. Corpo em JSON nos métodos POST, PUT e PATCH. A descrição completa, em OpenAPI 3.1, fica em /api/v1/openapi.json — dá para abrir no Postman, no Insomnia ou gerar um cliente.
curl -X POST https://claudo.com.br/api/v1/projects/loja/deployments \
-H "Authorization: Bearer $CLAUDO_TOKEN"
curl -X PUT https://claudo.com.br/api/v1/projects/loja/env/API_KEY \
-H "Authorization: Bearer $CLAUDO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"value":"…","environment":"production"}'- 400 — argumentos inválidos (invalid_request, invalid_json) ou recusa da regra
- 401 — sem token, token vencido ou revogado (invalid_token)
- 403 — papel ou escopo insuficiente, limite do plano, organização suspensa
- 404 — projeto, organização ou recurso não existe entre os seus
- 409 — conflito: nome em uso, recurso já existe, outra operação em andamento
- 429 — muitas chamadas: 300 a cada 5 minutos por token (cabeçalho Retry-After)
- 502 / 503 — o provedor de infraestrutura falhou ou não está ligado
Rotas
Conta
- GET/meQuem sou euleitura
- GET/platformO que a CLAUDO já fazleitura
- GET/usageConsumo da organizaçãoleitura
- GET/activityVer atividadeleitura
Organizações
- POST/organizationsCriar organização de equipeescrita
- GET/membersListar membrosleitura
- POST/membersConvidar membroescrita
- PATCH/members/{email}Mudar papel de membroescrita
- DELETE/members/{email}Remover membroescrita
Projetos
- GET/projectsListar projetosleitura
- POST/projectsCriar projetoescrita
- GET/projects/{project}Ver projetoleitura
- PATCH/projects/{project}Alterar projetoescrita
- DELETE/projects/{project}Apagar projetoescrita
- PUT/projects/{project}/kindTipo do projeto (web ou worker)escrita
- GET/github/repositoriesRepositórios do GitHubleitura
- PUT/projects/{project}/repositoryLigar repositório ao projetoescrita
- PUT/projects/{project}/repository/publicLigar repositório público ao projetoescrita
- PUT/projects/{project}/imageLigar imagem Docker ao projetoescrita
- PUT/projects/{project}/access-protectionPôr senha de acesso no siteescrita
- DELETE/projects/{project}/access-protectionTirar a senha de acesso do siteescrita
- PUT/projects/{project}/status-pagePágina de status públicaescrita
Deploy
- GET/deploymentsListar deploysleitura
- GET/projects/{project}/deploymentsListar deploysleitura
- POST/projects/{project}/deploymentsPublicar projetoescrita
- GET/deployments/{deployment_id}Ver deployleitura
- GET/projects/{project}/deploy-hooksListar ganchos de deployleitura
- POST/projects/{project}/deploy-hooksCriar gancho de deployescrita
- DELETE/projects/{project}/deploy-hooks/{hook_id}Apagar gancho de deployescrita
- POST/projects/{project}/restartReiniciar aplicaçãoescrita
- POST/projects/{project}/stopParar aplicaçãoescrita
- POST/projects/{project}/startLigar aplicaçãoescrita
- POST/deployments/{deployment_id}/rollbackVoltar para uma versão anteriorescrita
- GET/projects/{project}/logsLogs da aplicaçãoleitura
- GET/projects/{project}/logs/historyBuscar nos logs guardadosleitura
- GET/log-drainsListar envios de logsleitura
- GET/projects/{project}/log-alertsListar alertas de logleitura
- POST/projects/{project}/log-alertsCriar alerta de logescrita
- DELETE/projects/{project}/log-alerts/{alert_id}Apagar alerta de logescrita
- POST/log-drainsCriar envio de logsescrita
- DELETE/log-drains/{drain_id}Apagar envio de logsescrita
- GET/projects/{project}/monitoringDisponibilidade da aplicaçãoleitura
Variáveis
- GET/projects/{project}/envListar variáveis de ambienteleitura
- GET/projects/{project}/env/developmentBaixar variáveis de Developmentescrita
- POST/projects/{project}/env/importImportar variáveis de um .envescrita
- PUT/projects/{project}/env/{key}Definir variável de ambienteescrita
- DELETE/projects/{project}/env/{key}Apagar variável de ambienteescrita
- GET/shared-envListar variáveis compartilhadasleitura
- PUT/shared-env/{key}Definir variável compartilhadaescrita
- DELETE/shared-env/{key}Apagar variável compartilhadaescrita
Domínios
- GET/projects/{project}/domainsDomínios do projetoleitura
- POST/projects/{project}/domainsAdicionar domínioescrita
- POST/domains/{domain_id}/verifyVerificar domínioescrita
- PUT/projects/{project}/www-redirectRedirecionar wwwescrita
Bancos
- GET/databasesBancos de dadosleitura
- POST/projects/{project}/databasesCriar banco de dadosescrita
- GET/databases/{database}/backupsBackups de um bancoleitura
- POST/databases/{database}/backupsFazer backup agoraescrita
- POST/databases/{database}/passwordTrocar a senha do bancoescrita
- POST/databases/{database}/publicAbrir ou fechar o acesso de fora ao bancoescrita
- GET/projects/{project}/supabaseVer o Supabase do projetoleitura
- POST/projects/{project}/supabaseCriar Supabase no projetoescrita
Storage
- GET/bucketsListar buckets de storageleitura
- POST/projects/{project}/bucketsCriar bucket de storageescrita
Tarefas
- GET/projects/{project}/tasksTarefas do projetoleitura
- POST/projects/{project}/tasksCriar tarefaescrita
- POST/tasks/{task}/runsRodar tarefa agoraescrita
- GET/tasks/{task}/runsExecuções de uma tarefaleitura
- GET/projects/{project}/volumesVolumes do projetoleitura
- POST/projects/{project}/volumesCriar volumeescrita
Produtos
- GET/projects/{project}/analyticsVisitas do site do projetoleitura
- GET/mailE-mail da organização (CLAUDO Mail)leitura
- GET/queuesFilas e agendamentos (CLAUDO Queues)leitura
- GET/authLogin das aplicações (CLAUDO Auth)leitura
- GET/ai/usageUso do AI Gatewayleitura
CLAUDO Auth: login dos usuários das suas aplicações
Ligado por projeto no painel (Auth). Cada aplicação tem um emissor próprio, https://claudo.com.br/api/auth/<client_id>, gravado em CLAUDO_AUTH_URL. Ele é um provedor OpenID Connect completo: descoberta em /.well-known/openid-configuration, código com PKCE (S256), id_token e tokens em RS256, chaves públicas em /.well-known/jwks.json, userinfo e saída. Funciona com Auth.js, openid-client, oidc-client-ts e AppAuth no celular.
# Página de login da CLAUDO (OpenID Connect)
GET {issuer}/authorize?client_id=…&redirect_uri=…&response_type=code
&scope=openid email profile&code_challenge=…&code_challenge_method=S256&state=…
POST {issuer}/token grant_type=authorization_code | refresh_token
GET {issuer}/userinfo Authorization: Bearer <access_token>
GET {issuer}/logout ?post_logout_redirect_uri=…
# Tela própria (JSON)
POST {issuer}/signup { email, password, name? }
POST {issuer}/signin { email, password }
POST {issuer}/signout { refresh_token }
POST {issuer}/recover { email }
POST {issuer}/otp/send { email } · POST {issuer}/otp/verify { email, code }
POST {issuer}/mfa/verify { mfa_token, code } (quando o login devolve mfa_required)
POST {issuer}/mfa/totp/enroll · /mfa/totp/confirm { code } · /mfa/totp/disable { code }
GET {issuer}/user Authorization: Bearer <access_token>
# Servidor da aplicação (chave secreta claudo_auth_sk_)
GET|POST {issuer}/admin/users · GET|PATCH|DELETE {issuer}/admin/users/{id}O token de acesso vem com typ: at+jwt; o id_token só diz quem entrou e não serve na API. O token de renovação troca a cada uso; usar de novo um já trocado encerra a sessão. Sem PKCE, a troca do código exige a chave secreta (client_secret). Pelo navegador, só os sites cadastrados nos ajustes chamam a API. Quando o servidor da aplicação chama em nome do usuário, ele informa o endereço real em x-claudo-user-ip junto com a chave secreta, para o limite de tentativas valer por pessoa. Entrar com Google e GitHub usa o app OAuth da sua organização.
Status da plataforma
O estado de cada parte da CLAUDO, conferido a cada minuto, fica em /status e, para monitores, em JSON em /api/status, sem token.