API

API HTTP para proyectos, apps y el resto de la plataforma.

Cada recurso que ves en el dashboard tiene un endpoint HTTP. Úsalo desde la CLI, la CI, scripts o cualquier cliente que pueda enviar JSON.

• URL base: https://api.nodion.com
• Documentación interactiva: api.nodion.com/v2/docs
• OpenAPI: api.nodion.com/v2/openapi.yaml

Autenticación

Envía un token Bearer en cada petición:

httpAuthorization: Bearer nodion_…

Hay dos tipos de token:

• Las claves de API personales (nodion_…) actúan en tu nombre. Eliges los permisos y puedes limitar la clave a proyectos concretos. Créalas en Account → Security. El token se muestra una sola vez.
• Las claves de proyecto (nodion_proj_…) pertenecen a un proyecto, no a una persona, así que CI sigue funcionando cuando alguien se va. Créalas en la pestaña API keys del proyecto.

Permisos de una clave personal:

• read: listar y obtener recursos
• write: crear, actualizar y borrar
• deploy: lanzar despliegues
• env:read / env:write: valores de las variables de entorno
• logs:read: logs de las aplicaciones

Las lecturas necesitan read y las escrituras write, salvo que una operación exija un permiso más restringido (por ejemplo, deploy). Las claves de proyecto no tienen scopes: pueden hacerlo todo en ese proyecto. La facturación y el 2FA se quedan en el dashboard; las claves de API no pueden acceder a ellos.

Elige un proyecto

Las rutas anidadas tienen la forma /v2/projects/{id}/…. Si trabajas dentro de un proyecto, usa la ruta corta y envía el ID del proyecto en una cabecera:

httpX-Nodion-Project: prj_…

Primera petición

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

Lanza un despliegue (necesita el permiso deploy en una clave personal):

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

Listas, errores y límites

Las respuestas de colecciones tienen la forma { "data": [ … ], "next_cursor": null }. Para paginar, pasa ?limit= y el next_cursor anterior como ?cursor=.

Los errores usan RFC 9457 (application/problem+json) con un code estable y un request_id. Indica ese ID al soporte. El catálogo público es GET /v2/errors.

Las llamadas autenticadas con una clave tienen rate limit por cuenta. Las respuestas incluyen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 429 también envía Retry-After. Todas las respuestas llevan X-Request-Id.

Para los cuerpos de las peticiones y una consola para probarlas, usa la documentación interactiva. Las páginas siguientes muestran esos mismos endpoints con el formato de este sitio.

Endpoints

Esta lista, generada a partir del documento OpenAPI público, contiene 278 operaciones, agrupadas como en la especificación.