Resumen de la API

Todo lo que puedes hacer en el panel, puedes hacerlo por HTTP: espacios de trabajo, aplicaciones, despliegues, dominios, variables, miembros. Es la misma API a la que llama el propio panel.

URL base

https://cloady.com/api

Todas las solicitudes y respuestas son application/json. Envía Content-Type: application/json en cualquier solicitud con cuerpo.

Autenticación

Autentícate con un token de API personal. Pásalo como token bearer:

Authorization: Bearer cldy_...

Un token actúa como tú: accede a los espacios de trabajo a los que perteneces, con el rol que tienes en cada uno. El secreto se muestra una sola vez, al crearlo, y no se puede recuperar después: si lo pierdes, revócalo y crea uno nuevo.

Un token puede tener caducidad (never, 30d, 90d, 1y) y se puede revocar en cualquier momento. Un token ausente, mal formado, caducado o revocado recibe 401 unauthorized.

Un token también puede estar anclado a un solo espacio de trabajo. Entonces, las solicitudes a cualquier otro espacio de trabajo devuelven 403 forbidden, sea cual sea tu rol allí.

Tu cuenta debe tener un número de teléfono verificado; sin él, todos los endpoints autenticados devuelven 403 phone_required. Verifícalo una vez en Account → Security, en el panel.

Crear un token

Desde el panel: Account → API tokens (consulta la guía del panel). Elige un nombre, un alcance y una caducidad. El secreto solo se muestra una vez, así que cópialo enseguida. Para crear un token hace falta, a su vez, el alcance full o una sesión iniciada en el navegador.

Alcances de los tokens

Cada token se crea con un único alcance, que limita lo que puede hacer:

• read: solo lectura. Listar e inspeccionar espacios de trabajo, aplicaciones, despliegues y logs. Sin cambios.
• deploy: todo lo que puede hacer read, más lo que hace un developer. Puede desplegar, redesplegar, iniciar, detener y reiniciar, gestionar dominios y variables, y eliminar una aplicación (lo que borra sus datos de forma permanente).
• full: sin restricciones. Todo lo que puede hacer deploy, más las acciones de administración: crear espacios de trabajo, ajustes del espacio de trabajo, miembros, integraciones y facturación.

Elige el alcance más reducido que cubra tu caso de uso: una clave de despliegue para CI necesita deploy, no full.

Roles en el espacio de trabajo

El alcance limita el token; tu rol en el espacio de trabajo limita la solicitud. Los endpoints de un espacio de trabajo exigen un rol mínimo. De menor a mayor:

• viewer: ver el espacio de trabajo y sus aplicaciones.
• developer: desplegar y operar aplicaciones, lo que incluye despliegues, reinicios, logs, shell, base de datos, dominios y variables, y eliminar una aplicación.
• admin: gestionar los ajustes del espacio de trabajo, los miembros, las integraciones y el inicio de sesión único.
• owner: todo, incluidas la facturación y la eliminación del espacio de trabajo.

Una solicitud por debajo del rol mínimo del endpoint devuelve 403 forbidden. Un espacio de trabajo del que no eres miembro devuelve 404 not_found: nunca se revela la membresía.

Parámetros env y region en la consulta

Cada aplicación se ejecuta en una región y en un entorno (production, preview o development), y su nombre es único dentro de un espacio de trabajo y un entorno. Las URL del panel llevan la región y el entorno como segmentos de ruta, pero las solicitudes a la API los llevan como parámetros de consulta:

?env=<production|preview|development>&region=<regionId>

• env vale production si se omite.
• region es opcional y rara vez hace falta. Pásalo solo cuando el mismo nombre exista en más de una región: esas solicitudes devuelven 400 region_required, y tienes que reintentar con ?region=.

GET /api/workspaces/acme/apps/my-blog?env=production&region=usw1

Los ids de región se obtienen con GET /api/regions. Cualquier espacio de trabajo puede desplegar en cualquiera de ellas; la región se elige al desplegar la aplicación.

En estas rutas, las aplicaciones y los espacios de trabajo se identifican por su nombre, y la dirección pública de una aplicación también sigue a su nombre, así que renombrar cambia tanto la URL a la que llamas como la URL en la que se sirve tu app. Actualiza los scripts que hagan referencia al nombre antiguo. Aun así, renombrar es la opción segura: eliminar una aplicación borra sus datos de forma permanente.

Endpoints de streaming

El estado de las apps, las métricas, el progreso y los logs de los despliegues y los mensajes de los tickets se transmiten como server-sent events. Envía Accept: text/event-stream para recibir el flujo en directo; sin esa cabecera recibes el estado actual una sola vez, como JSON normal, que es lo que necesita un script. Los logs de los servicios hacen lo mismo: a una solicitud normal responden con las últimas 200 líneas.

Formato de los errores

Los errores incluyen un code legible por máquinas:

{ "error": { "code": "not_found", "message": "App my-blog not found" } }

Lee el código en body.error.code y decide según ese valor, nunca según el mensaje ni solo según el código de estado. Los errores de validación (bad_body) añaden un array details con los campos incorrectos.

Ejemplo

Lista tus espacios de trabajo:

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_..."

{
  "workspaces": [ /* ... */ ]
}

Para ver el catálogo completo de endpoints (rutas, métodos, parámetros y cuerpos), consulta las páginas de endpoints de la barra lateral, empezando por listWorkspaces.