Como um agent usa isto

Um agent usa a API /v1 em um laço simples:

Autenticar: Authorization: Bearer $NEBULAR_TOKEN. O token vem de variável de ambiente, nunca do texto do prompt nem de arquivo versionado. Confirme escopos e limites com GET /v1/me (Token de API).
Agir com Idempotency-Key em todo POST que cria, para que repetir seja seguro.
Esperar quando a resposta for assíncrona: upload 202 pending (Uploads pending) ou deploy queued. Consulte o recurso com backoff (2 s, dobrando até 30 s); não reenvie.
Ler o erro pelo campo error e decidir pela tabela de erros:
- 4xx (exceto 429): corrija a requisição; não repita igual.
- 429, 503: repita depois de Retry-After (ou com backoff).
- 401/403: pare e peça um token novo ou com o escopo certo a uma pessoa.
- 404: o recurso não existe ou não é do seu time; a API não distingue. Confira o id; não tente descobrir.
Parar e pedir uma pessoa quando o erro exigir decisão humana (malware_detected, quota_exceeded, deploy failed sem causa clara nos logs).

Laço de deploy

POST /v1/projects e POST .../services (veja Primeiro deploy).
Variáveis e, se preciso, banco e volume (Variáveis e referências, PostgreSQL).
POST .../deployments (ou POST /v1/projects/{p}/deploy para o grupo).
Polling de GET .../deployments/{d} até ready (para o grupo, GET /v1/projects/{p}/group-deployments/{g} até status sair de running; ready é sucesso). Estado failed, blocked, canceled ou superseded: pare e leia o log de build (Logs).
Verifique a URL pública. Se falhar, rollback para o deploy anterior e reporte.