API

API HTTP per progetti, app e il resto della piattaforma.

Ogni risorsa che vedi nella dashboard ha un endpoint HTTP. Usalo dalla CLI, in CI, da script o da qualsiasi client in grado di inviare JSON.

• URL base: https://api.nodion.com
• Documentazione interattiva: api.nodion.com/v2/docs
• OpenAPI: api.nodion.com/v2/openapi.yaml

Autenticazione

Invia un bearer token in ogni richiesta:

httpAuthorization: Bearer nodion_…

Esistono due tipi di token:

• Le chiavi API personali (nodion_…) agiscono a tuo nome. Scegli gli scope e puoi limitare la chiave a progetti specifici. Creale in Account → Security. Il token viene mostrato una sola volta.
• Le chiavi di progetto (nodion_proj_…) appartengono a un progetto, non a una persona, così la CI continua a funzionare quando qualcuno se ne va. Creale nella scheda API keys del progetto.

Scope di una chiave personale:

• read: elencare e leggere le risorse
• write: creare, modificare ed eliminare
• deploy: avviare i deploy
• env:read / env:write: valori delle variabili d'ambiente
• logs:read: log delle applicazioni

Le letture richiedono read, le scritture write, a meno che un'operazione non chieda uno scope più ristretto (ad esempio deploy). Le chiavi di progetto non hanno scope: possono fare tutto in quel progetto. Fatturazione e 2FA restano nella dashboard; le chiavi API non possono accedervi.

Scegli un progetto

Le route annidate hanno la forma /v2/projects/{id}/…. Se lavori in un solo progetto, usa il percorso breve e invia l'ID del progetto come header:

httpX-Nodion-Project: prj_…

Prima richiesta

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

Avvia un deploy (richiede lo scope deploy su una chiave personale):

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

Liste, errori e limiti

Le risposte agli elenchi hanno la forma { "data": [ … ], "next_cursor": null }. Per paginare passa ?limit= e il next_cursor precedente come ?cursor=.

Gli errori usano RFC 9457 (application/problem+json) con un code stabile e un request_id. Comunica quell'ID al supporto. Il catalogo pubblico è GET /v2/errors.

Le chiamate autenticate con una chiave hanno un rate limit per account. Le risposte includono RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Una risposta 429 include anche Retry-After. Ogni risposta ha X-Request-Id.

Per i body delle richieste e una console per provarle, usa la documentazione interattiva. Le pagine qui sotto mostrano gli stessi endpoint, nello stile di questo sito.

Endpoint

Generati dal documento OpenAPI pubblico. 278 operazioni, raggruppate come nella specifica.