Pular para o conteúdo
- Base URL:
https://api.nebularws.com; todas as rotas ficam em /v1.
- Autenticação:
Authorization: Bearer nbk_…, nunca em query string. Cookies são ignorados. Veja Token de API.
- Erros: sempre
{"error": "<codigo>", "message": "..."}. Trate pelo error (estável); mostre o message (pt-BR) a pessoas. Veja a tabela de erros.
- 404 anti-IDOR: recurso inexistente e recurso de outro time/projeto respondem igual (
404 not_found). 401 é genérico de propósito. 403 só aparece quando o recurso é seu e falta escopo. Não tente distinguir.
- Paginação por cursor: listas devolvem
items, next_cursor e has_more. Siga next_cursor enquanto has_more for true; o cursor é opaco. Receita em Galerias e arquivos.
- Idempotência: todo
POST que cria ou dispara aceita Idempotency-Key (8 a 128 caracteres [A-Za-z0-9._:-]). Mesma chave e mesmo pedido em 24 h devolve a mesma resposta (cabeçalho Idempotent-Replay: true); mesma chave com outro pedido dá 422 idempotency_conflict (409 no upload de galeria); chave malformada (fora de 8 a 128 caracteres [A-Za-z0-9._:-]), 400 invalid_request. Só respostas 2xx são gravadas. Veja Galerias e arquivos.
- Corpo JSON: todo
POST/PUT/PATCH com corpo leva Content-Type: application/json. Regra exata para POST /v1/projects/{p}/deploy, POST .../services/{s}/deployments e POST .../deployments/{d}/rollback: o corpo é opcional. Sem corpo (ou Content-Length: 0), com ou sem Content-Type, vale {}; com corpo, ele tem de ser JSON com Content-Type: application/json (outro tipo, como text/plain ou formulário, dá 415 unsupported_media_type); o deploy de serviço aceita também multipart/form-data (campo file). Os exemplos mandam Content-Type: application/json e {} por ser a forma que funciona em qualquer cliente HTTP. Todo projeto nasce com um serviço web padrão, público e com slug (Conceitos).
- Rate limit: por token e por IP; em
429 espere Retry-After segundos. Veja Rate limit e retry.
- Ids: opacos. Projetos, serviços, deploys, bancos e demais recursos da v13 usam ULID em minúsculas de 26 caracteres (por exemplo
01m4kxaxjts58n5esjajbr5pg0); galerias e arquivos têm prefixo do tipo (gal_…, ast_…, ver_…). Não os interprete nem dependa do formato: use o que a API devolveu.
- Datas: RFC 3339 em UTC (
2026-10-09T14:03:11Z).
- Assíncrono: deploys, backups e restores respondem logo e terminam depois; consulte o recurso com backoff. Não há webhooks neste ciclo.
- Estados de deploy:
queued, building, deploying, ready, failed, blocked, canceled, superseded. Terminais: todos menos queued, building e deploying. Veja Deploys e status.
- Limites do token e do time:
GET /v1/me e GET /v1/limits.