Referencia

Referencia de la API

Todo lo que hacen la consola y la CLI pasa por esta API. Es una interfaz HTTP sencilla en JSON que se autentica con un bearer token.

URL base

https://console.codaracloud.com

Autenticación

Envía un token de API como bearer token en cada petición. Créalo en Cuenta y organización → Tokens de API o con codaracloud token create. Consulta Obtener acceso.

bash

$ curl -H "Authorization: Bearer cdr_live_xxxxxxxx" \    https://console.codaracloud.com/v1/apps

Un token solo puede acceder a lo que permiten sus scopes. Una petición fuera de ellos devuelve 403 e indica el scope que hacía falta.

Las excepciones a la autenticación son pocas

El health check y las rutas de inicio de sesión interactivo son públicas. Los webhooks de GitHub y los callbacks del sistema de build usan su propia autenticación de servicio. Las rutas que gestionan recursos exigen una sesión de navegador o un bearer token.

Convenciones

Esta página es un índice práctico

Las tablas siguientes cubren los endpoints que más se usan; no son un listado exhaustivo del esquema. El openapi.json generado en el paquete de la API de la plataforma es el contrato de referencia legible por máquinas.

Ámbito

La mayoría de los recursos están dentro de un espacio de trabajo (el client de la API), un proyecto y un entorno. Identifícalos con parámetros de consulta:

bash

$ curl -H "Authorization: Bearer $CODARA_TOKEN" \    "https://console.codaracloud.com/v1/apps?client_slug=my-workspace&project_slug=website&environment_slug=production"

En los endpoints de lectura, si no indicas el ámbito se usan tu espacio de trabajo por defecto y el entorno production. Cuando un nombre es ambiguo entre proyectos, la API devuelve 409 y te pide que lo concretes.

Al crear un recurso, la API no adivina el proyecto

POST /v1/apps y POST /v1/jobs solo resuelven project_slug cuando el espacio de trabajo tiene exactamente un proyecto. Si tiene más de uno, la petición se rechaza con workspace_required y el mensaje enumera los candidatos: no elige uno por ti. Si no tiene ninguno, recibes no_workspace y se te indica que crees uno primero.

Un proyecto suele ser un producto con su propio repositorio, así que lo normal es crear un proyecto nuevo en lugar de reutilizar uno que ya existe.

Usa el campo slug, no el nombre visible

Los recursos pueden tener un slug físico y además un valor visible más amigable. Identifica siempre los recursos por el campo slug que devuelve la API.

Respuestas de listas

La mayoría de los endpoints de colecciones devuelven un objeto envoltorio con un cursor para paginar:

json

{  "items": [ … ],  "next_cursor": null}

No todos los endpoints de listas usan este formato (algunos devuelven un array con otro nombre), así que lee el campo que recibes en lugar de darlo por supuesto.

Errores

Los errores son JSON con un código legible por máquinas y un mensaje para personas:

json

{  "error": "not_found",  "message": "app 'my-api' not found"}

Estado	Significado
400	Petición no válida. Normalmente `bad_request`.
401	Credencial ausente, no válida o caducada.
403	Autenticado, pero al token le falta el scope necesario.
404	No existe ese recurso en el ámbito que has pedido.
402	El plan no lo permite: `plan_limit_exceeded` (indica el límite, con el valor permitido y el actual), `plan_feature_unavailable` o `subscription_not_active`.
409	Conflicto: un nombre que ya está en uso, una búsqueda ambigua o una condición previa que no se cumple.
503	Una dependencia no estaba disponible temporalmente. Vuelve a intentarlo.

Identidad

	Endpoint	Para qué sirve
GET	/v1/me	El usuario actual y los espacios de trabajo que puede ver.
GET	/v1/tokens	Lista los tokens de API.
POST	/v1/tokens	Crea un token. El secreto se devuelve una sola vez.
DELETE	/v1/tokens/{id}	Revoca un token.

Apps

	Endpoint	Para qué sirve
GET	/v1/apps	Lista las apps.
POST	/v1/apps	Crea una app. Indica de forma explícita el espacio de trabajo, el proyecto y el entorno siempre que el nombre pudiera ser ambiguo.
GET	/v1/apps/{name}	Detalle de la app.
PATCH	/v1/apps/{name}	Actualiza el runtime, el origen o la política.
DELETE	/v1/apps/{name}	Elimina una app.
PUT	/v1/apps/{name}/image	Apunta a una nueva referencia de imagen.
PUT	/v1/apps/{name}/autosleep	Configura cuándo se duerme la app automáticamente.
GET	/v1/apps/{name}/connections	Bases de datos, apps privadas y buckets conectados a la app.

Crear una app no lanza su build

POST /v1/apps deja una app vinculada a un repositorio apuntando a una imagen provisional. Envía después una petición de build o la app no arrancará nunca.

Builds y deploys

	Endpoint	Para qué sirve
POST	/v1/apps/{name}/builds	Lanza un build. Es el endpoint que inicia una release.
GET	/v1/apps/{name}/deploys	Historial de deploys.
GET	/v1/apps/{name}/deploys/{deploy_id}	Detalle de un deploy.
GET	/v1/apps/{name}/deploys/{deploy_id}/logs	Salida del build. Vacía pasadas 24 horas.
POST	/v1/apps/{name}/deploys/{deploy_id}/cancel	Cancela antes de la promoción.
POST	/v1/apps/{name}/deploys/{deploy_id}/rollback	Vuelve a publicar la imagen de este deploy. Solo se pueden restaurar los 10 últimos deploys completados con éxito de la app, mientras su imagen siga existiendo.
POST	/v1/apps/{name}/deploys/{deploy_id}/promote-to-environment	Promueve a otro entorno.

Usa /builds para iniciar una release

Lanza los builds a partir del código con /v1/apps/{name}/builds. En el contrato de producción no existe ninguna ruta pública POST /v1/apps/{name}/deploys.

Configuración

	Endpoint	Para qué sirve
GET	/v1/apps/{name}/env	Lista las variables. Los valores aparecen enmascarados.
PATCH	/v1/apps/{name}/env	Define y elimina varias a la vez en una sola petición, con `{ set, unset }`.
GET	/v1/apps/{name}/env/{key}	Muestra un valor. Requiere `env:reveal`. Queda registrado en el log de auditoría.

bash

$ curl -X PATCH \    -H "Authorization: Bearer $CODARA_TOKEN" \    -H "content-type: application/json" \    -d '{"set":{"LOG_LEVEL":"debug"},"unset":["OLD_KEY"]}' \    https://console.codaracloud.com/v1/apps/my-api/env

Bases de datos, almacenamiento y jobs

	Endpoint	Para qué sirve
GET	/v1/databases	Lista las bases de datos.
POST	/v1/databases	Crea una base de datos.
GET	/v1/databases/{name}/connection	Datos de conexión.
GET	/v1/databases/{name}/backups	Lista las copias de seguridad.
POST	/v1/databases/{name}/backup	Hace una copia de seguridad ahora. Solo PostgreSQL y Redis dedicado.
GET	/v1/buckets	Lista los buckets de almacenamiento de objetos.
POST	/v1/buckets	Crea un bucket de almacenamiento de objetos. Ningún plan de autoservicio incluye buckets; necesitan un acuerdo aparte.
GET	/v1/jobs	Lista los jobs.
POST	/v1/jobs	Crea un job puntual o programado.
PATCH	/v1/jobs/{name}	Cambia la imagen OCI de un job programado o suspende sus próximas ejecuciones, o ambas cosas.
GET	/v1/apps/{name}/volumes	Volúmenes conectados a una app.

Las métricas de bases de datos necesitan dos scopes

Para leer /v1/databases/{name}/metrics hace falta un scope de lectura de bases de datos y metrics:read.

Dominios, logs, métricas y coste

	Endpoint	Para qué sirve
GET	/v1/apps/{name}/domains	Hostnames con el estado actual del DNS y del certificado.
POST	/v1/apps/{name}/domains	Asocia un hostname.
DELETE	/v1/apps/{name}/domains/{host}	Quita un hostname.
GET	/v1/apps/{name}/logs	Últimas líneas de los logs de ejecución.
GET	/v1/apps/{name}/metrics	CPU, memoria, réplicas y reinicios.
GET	/v1/cost/summary	Solo para operadores: resumen en directo de OpenCost del clúster y de los espacios de trabajo.
GET	/v1/cost/clients/{slug}	Solo para operadores: reparto de OpenCost de un espacio de trabajo.
GET	/v1/cost/clients/{slug}/invoices	Solo para operadores: registro interno de costes mensuales.

Conviene consultar el estado del dominio

El POST que asocia un dominio responde con éxito de forma optimista mientras el DNS y el certificado todavía se están preparando. La señal fiable de que está listo es el campo de estado de GET /v1/apps/{name}/domains.

Espacios de trabajo (clients) y proyectos

	Endpoint	Para qué sirve
GET	/v1/clients	Lista los espacios de trabajo.
POST	/v1/clients	Crea un espacio de trabajo vacío. Los proyectos se crean aparte.
PATCH	/v1/clients/{client}	Actualiza un espacio de trabajo.
GET	/v1/clients/{client}/deletion-preflight	Lista de comprobación para eliminar un espacio de trabajo: lo que bloquea cada proyecto y el almacenamiento conservado del propio espacio de trabajo, cada punto con su solución.
DELETE	/v1/clients/{client}	Elimina un espacio de trabajo vacío (y con él sus proyectos y entornos). Devuelve 409 con la lista de comprobación mientras quede algo; nunca elimina datos en cascada.
GET	/v1/clients/{slug}/projects	Lista los proyectos.
POST	/v1/clients/{slug}/projects	Crea un proyecto.
GET	/v1/clients/{slug}/projects/{project}/environments	Lista los entornos.
GET	/v1/clients/{slug}/projects/{project}/deletion-preflight	Lista de comprobación para eliminar: cada app (con datos en volúmenes), base de datos, job, bucket y almacenamiento conservado que sigue bloqueando la eliminación, cada uno con su solución.
GET	/v1/clients/{slug}/projects/{project}/environments/{env}/deletion-preflight	La misma lista para un entorno, más sus comprobaciones de entorno por defecto y de origen de previews.
DELETE	/v1/clients/{slug}/projects/{project}	Elimina un proyecto vacío (y con él sus entornos). Devuelve 409 con la lista de comprobación mientras quede algo; nunca elimina datos en cascada.
GET	/v1/clients/{client}/quotas	Solo para operadores: límite interno de gasto y modo de aplicación.

Evita las rutas de entornos a nivel de espacio de trabajo

Los endpoints antiguos del tipo /v1/clients/{slug}/environments siguen existiendo, pero dan por hecho que hay un proyecto llamado default y, si no, se comportan de forma incorrecta. Usa las rutas por proyecto de arriba.

Lo que no está en la API

Algunas cosas quedan fuera del contrato público a propósito y no deben llamarse directamente: las redirecciones del inicio de sesión con OAuth, el webhook de GitHub y los callbacks internos que usa el sistema de build.

Última actualización: 26 de septiembre de 2026