API

API HTTP para projetos, aplicações e o resto da plataforma.

Cada recurso que vê no dashboard tem um endpoint HTTP. Use-o a partir da CLI, de CI, de scripts ou de qualquer cliente capaz de enviar JSON.

• URL base: https://api.nodion.com
• Documentação interativa: api.nodion.com/v2/docs
• OpenAPI: api.nodion.com/v2/openapi.yaml

Autenticação

Envie um bearer token em cada pedido:

httpAuthorization: Bearer nodion_…

Existem dois tipos de token:

• As chaves de API pessoais (nodion_…) atuam em seu nome. Escolha os scopes e, se quiser, limite a chave a projetos específicos. Crie-as em Account → Security. O token só é mostrado uma vez.
• As chaves de projeto (nodion_proj_…) pertencem a um projeto e não a uma pessoa, para que a CI continue a funcionar quando alguém sai. Crie-as no separador API keys do projeto.

Scopes de uma chave pessoal:

• read: listar e obter recursos
• write: criar, atualizar e eliminar
• deploy: iniciar deploys
• env:read / env:write: valores das variáveis de ambiente
• logs:read: logs das aplicações

As operações de leitura exigem read e as de escrita, write, exceto quando uma operação exige um scope mais restrito (por exemplo, deploy). As chaves de projeto não têm scopes. Podem fazer tudo nesse projeto. A faturação e a 2FA ficam no dashboard; as chaves de API não têm acesso a estas funções.

Escolher um projeto

As rotas aninhadas têm a forma /v2/projects/{id}/…. Se trabalhar num só projeto, use o caminho curto e envie o ID do projeto no cabeçalho:

httpX-Nodion-Project: prj_…

Primeiro pedido

bashcurl https://api.nodion.com/v2/applications \
  -H "Authorization: Bearer $NODION_TOKEN" \
  -H "X-Nodion-Project: $NODION_PROJECT"

Iniciar um deploy (requer o scope deploy numa chave pessoal):

bashcurl -X POST https://api.nodion.com/v2/applications/$APP_ID/deployments \
  -H "Authorization: Bearer $NODION_TOKEN"

Listas, erros e limites

As respostas de coleções têm a forma { "data": [ … ], "next_cursor": null }. Para paginar, passe ?limit= e o next_cursor anterior como ?cursor=.

Os erros seguem a especificação RFC 9457 (application/problem+json) com um code estável e um request_id. Indique esse ID ao suporte. O catálogo público está em GET /v2/errors.

As chamadas autenticadas com chave estão sujeitas a um rate limit por conta. As respostas incluem RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Uma resposta 429 envia também Retry-After. Todas as respostas têm X-Request-Id.

Para os corpos dos pedidos e uma consola de testes, use a documentação interativa. As páginas abaixo mostram os mesmos endpoints, com o aspeto deste site.

Endpoints

Lista gerada a partir do documento OpenAPI público. 278 operações, agrupadas como na especificação.