Usar la API REST

La API REST de Skysize permite que tus scripts, tus pipelines de CI y tus herramientas de negocio operen los entornos de Odoo que ya tienes: relanzar un build después de un merge, seguir un build hasta que termine, leer logs y métricas, hacer una copia de seguridad antes de un cambio arriesgado o crear bajo demanda una nueva base de datos SaaS.

La API REST está disponible en los planes de pago. Consulta los precios para ver qué planes la incluyen.

Para la lista completa de endpoints, cuerpos de petición y respuestas, consulta la referencia de la API (en inglés).

Crear un token de API

Inicia sesión en app.skysize.io y abre Cuenta > Tokens de API.
Ponle al token un nombre que indique dónde se usa, por ejemplo ci-deploy.
En Uso, elige API REST. Un token sirve para un solo uso: crea otro distinto para un agente de IA (MCP).
Elige un nivel de Acceso. Solo lectura viene preseleccionado:
- Solo lectura: listar y leer todo lo que expone la API.
- Lectura y escritura: además, relanzar builds, reiniciar, hacer copias de seguridad, cambiar variables de entorno y ajustes de ramas, crear bases de datos.
- Completo, incluidas las acciones destructivas: además, eliminar, destruir un despliegue y restaurar una copia de seguridad.
Elige una caducidad y haz clic en Crear token.

El token se muestra una sola vez. Cópialo en ese momento; si lo pierdes, revócalo y crea uno nuevo.

atención

Un token actúa en tu nombre, en todos los proyectos a los que tienes acceso. Guárdalo en el almacén de secretos de tu CI, nunca en un repositorio, y dale el nivel de acceso más bajo que necesite la tarea.

Hacer una petición

Envía el token en la cabecera X-API-Token. La URL base es https://api.skysize.io/v1.

curl -H "X-API-Token: $SKYSIZE_TOKEN" https://api.skysize.io/v1/projects

Las peticiones y las respuestas son JSON. Los errores llegan como {"error": "<code>"} con el estado HTTP correspondiente:

Estado	Código	Significado
401	`unauthorized`	Token ausente, caducado o revocado
402	`api_requires_paid_plan`	El proyecto está en el plan gratuito
403	`insufficient_token_access`	El nivel de acceso del token es demasiado bajo para esta acción
403	`endpoint_not_available_via_token`	Esta acción solo está disponible en el panel
404	`project_not_found`, `branch_not_found`, ...	No existe, o no tienes acceso
429	`rate_limited`	Más de 120 peticiones en un minuto; reintenta después del plazo `Retry-After`

Qué cubre la API

La API opera entornos que ya existen:

Proyectos y ramas: leerlos, cambiar los ajustes de una rama, reiniciar, aplicar variables de entorno, actualizar la imagen de Odoo, destruir un despliegue.
Builds: listar, leer, relanzar el build de una rama, cancelar.
Logs y métricas: logs de build y de ejecución (en directo o descargados), búsqueda en los logs, consultas lentas, historial de CPU y memoria, disponibilidad y señales de salud.
Copias de seguridad: listar, hacer una copia manual, restaurar una copia en una rama.
Variables de entorno: listar, crear, modificar, eliminar. Los valores sensibles nunca se devuelven.
Bases de datos SaaS: listar, crear y eliminar las bases de datos de una rama en modo SaaS.
Tareas de la plataforma (logs de instalación, actualización, copia de seguridad y restauración): solo en proyectos Bring Your Own Server.

Se quedan en el panel: crear o eliminar proyectos y ramas, miembros y grupos, dominios personalizados, conexiones git, credenciales de copias de seguridad y almacenamiento, facturación y archivos de copia de seguridad (importar o descargar un archivo).

Seguir un log en directo

Los flujos de logs y de eventos usan server-sent events. Con curl, desactiva el búfer con -N:

curl -N -H "X-API-Token: $SKYSIZE_TOKEN" \
  https://api.skysize.io/v1/projects/$PROJECT_ID/branches/$BRANCH_ID/logs/stream

Cada línea data: es una línea de log en JSON. Un comentario : heartbeat llega cada 30 segundos para mantener la conexión abierta cuando no pasa nada.

Ejemplo: relanzar un build después de un merge

Una tarea de CI con un token de Lectura y escritura puede relanzar el build de la rama de staging y esperar el resultado:

API=https://api.skysize.io/v1
H="X-API-Token: $SKYSIZE_TOKEN"

build=$(curl -s -X POST -H "$H" -H "Content-Type: application/json" \
  -d "{\"branch_id\": \"$BRANCH_ID\"}" "$API/projects/$PROJECT_ID/builds")
echo "$build"

# Después consulta los builds de la rama hasta que el más reciente haya terminado.
curl -s -H "$H" "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/builds"

Un build fallido lleva un código failure_reason y, en failure_log, el log que muestra el problema.

Ejemplo: una base de datos de demo por cliente potencial

En una rama en modo SaaS, cada base de datos es su propia instancia de Odoo con su propia dirección. Un botón en tu CRM puede crear una base de datos para un cliente potencial, llenarla con datos de demo adecuados y eliminarla después de la demo.

Crea la base de datos (Lectura y escritura). El nombre se convierte en su dirección y debe ser único, así que añade un sufijo aleatorio corto:
```
curl -s -X POST -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "acme-demo-x7k2", "lang": "es_ES", "admin_password": "una-contrasena-larga-y-aleatoria"}' \
  "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/databases"
```
La respuesta incluye un id, la url de la base de datos (por ejemplo https://acme-demo-x7k2.skysize.io) y "pending": true.
Consulta GET .../databases/{id} con ese id hasta que pending desaparezca. Si todo va bien, obtienes la base de datos. Si la creación falló, la respuesta trae "failed": true y un failure_reason:
- db_name_taken: alguien tomó el nombre mientras tanto. Elige otro.
- create_failed: reintenta, y contacta con soporte si sigue fallando.
- cancelled: la creación se canceló.
Llénala con la API externa de Odoo (XML-RPC o JSON-RPC) en esa url, iniciando sesión como admin con la contraseña que elegiste: instala las aplicaciones de la demo y crea los clientes, productos y pedidos que correspondan al cliente potencial.
Después de la demo, elimínala (Completo): DELETE .../databases/{database_id}. Se hace una última copia de seguridad antes de eliminar la base de datos.

Cada base de datos de demo se ejecuta en el contenedor de la rama y usa sus workers y su almacenamiento, así que elimina las que ya no necesites.

Crear un token de API​

Hacer una petición​

Qué cubre la API​

Seguir un log en directo​

Ejemplo: relanzar un build después de un merge​

Ejemplo: una base de datos de demo por cliente potencial​