# Como um agent usa isto

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

1. **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](/comecar/token/)).
2. **Agir** com `Idempotency-Key` em todo `POST` que cria, para que repetir seja seguro.
3. **Esperar** quando a resposta for assíncrona: upload `202 pending` ([Uploads pending](/cdn/galerias/#uploads-pending-202-como-esperar)) ou deploy `queued`. Consulte o recurso com backoff (2 s, dobrando até 30 s); não reenvie.
4. **Ler o erro** pelo campo `error` e decidir pela [tabela de erros](/erros/tabela/):
   - `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.
5. **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

1. `POST /v1/projects` e `POST .../services` (veja [Primeiro deploy](/comecar/primeiro-deploy/)).
2. Variáveis e, se preciso, banco e volume ([Variáveis e referências](/conectados/variaveis-e-referencias/), [PostgreSQL](/bancos/postgres/)).
3. `POST .../deployments` (ou `POST /v1/projects/{p}/deploy` para o grupo).
4. 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](/operacao/logs/)).
5. Verifique a URL pública. Se falhar, [rollback](/operacao/rollback/) para o deploy anterior e reporte.

Fluxo de decisão completo: [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/). Receita pronta: [Do zero ao ar com um agent](/receitas/do-zero-ao-ar-com-um-agent/).