Utiliser l'API REST

L'API REST de Skysize permet à vos scripts, à vos pipelines de CI et à vos outils métier de piloter les environnements Odoo que vous avez déjà : relancer un build après un merge, suivre un build jusqu'à la fin, lire les logs et les métriques, faire une sauvegarde avant un changement risqué ou créer à la demande une nouvelle base SaaS.

L'API REST est disponible avec les offres payantes. Consultez les tarifs pour savoir quelles offres l'incluent.

Pour la liste complète des points d'accès, des corps de requête et des réponses, consultez la référence de l'API (en anglais).

Créer un jeton d'API

Connectez-vous à app.skysize.io et ouvrez Compte > Jetons d'API.
Donnez au jeton un nom qui indique où il sert, par exemple ci-deploy.
Sous Usage, choisissez API REST. Un jeton ne sert qu'à un seul usage : créez-en un autre pour un agent IA (MCP).
Choisissez un niveau d'Accès. Lecture seule est présélectionné :
- Lecture seule : lister et lire tout ce que l'API expose.
- Lecture et écriture : en plus, relancer un build, redémarrer, faire des sauvegardes, modifier les variables d'environnement et les réglages des branches, créer des bases.
- Complet, actions destructives comprises : en plus, supprimer, détruire un déploiement et restaurer une sauvegarde.
Choisissez une expiration et cliquez sur Créer le jeton.

Le jeton n'est affiché qu'une fois. Copiez-le à ce moment-là ; si vous le perdez, révoquez-le et créez-en un nouveau.

attention

Un jeton agit en votre nom, sur tous les projets auxquels vous avez accès. Rangez-le dans le coffre à secrets de votre CI, jamais dans un dépôt, et donnez-lui le niveau d'accès le plus bas dont la tâche a besoin.

Envoyer une requête

Envoyez le jeton dans l'en-tête X-API-Token. L'URL de base est https://api.skysize.io/v1.

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

Les requêtes et les réponses sont en JSON. Les erreurs reviennent sous la forme {"error": "<code>"} avec le statut HTTP correspondant :

Statut	Code	Signification
401	`unauthorized`	Jeton absent, expiré ou révoqué
402	`api_requires_paid_plan`	Le projet est sur l'offre gratuite
403	`insufficient_token_access`	Le niveau d'accès du jeton est trop bas pour cette action
403	`endpoint_not_available_via_token`	Cette action n'est disponible que dans le tableau de bord
404	`project_not_found`, `branch_not_found`, ...	Introuvable, ou vous n'y avez pas accès
429	`rate_limited`	Plus de 120 requêtes en une minute ; réessayez après le délai `Retry-After`

Ce que couvre l'API

L'API pilote des environnements qui existent déjà :

Projets et branches : les lire, modifier les réglages d'une branche, redémarrer, appliquer les variables d'environnement, mettre à jour l'image Odoo, détruire un déploiement.
Builds : lister, lire, relancer le build d'une branche, annuler.
Logs et métriques : logs de build et d'exécution (en direct ou en téléchargement), recherche dans les logs, requêtes lentes, historique CPU et mémoire, disponibilité et signaux de santé.
Sauvegardes : lister, faire une sauvegarde manuelle, restaurer une sauvegarde sur une branche.
Variables d'environnement : lister, créer, modifier, supprimer. Les valeurs sensibles ne sont jamais renvoyées.
Bases SaaS : lister, créer et supprimer les bases d'une branche en mode SaaS.
Tâches de la plateforme (logs d'installation, de mise à jour, de sauvegarde, de restauration) : uniquement sur les projets Bring Your Own Server.

Restent dans le tableau de bord : la création et la suppression de projets et de branches, les membres et les groupes, les domaines personnalisés, les connexions git, les identifiants de sauvegarde et de stockage, la facturation et les fichiers de sauvegarde (importer ou télécharger une archive).

Suivre un log en direct

Les flux de logs et d'événements utilisent les server-sent events. Avec curl, désactivez la mise en tampon avec -N :

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

Chaque ligne data: est une ligne de log en JSON. Un commentaire : heartbeat arrive toutes les 30 secondes pour garder la connexion ouverte quand rien ne se passe.

Exemple : relancer un build après un merge

Une tâche de CI avec un jeton Lecture et écriture peut relancer le build de la branche de staging et attendre le résultat :

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"

# Puis interrogez les builds de la branche jusqu'à ce que le plus récent soit terminé.
curl -s -H "$H" "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/builds"

Un build en échec porte un code failure_reason et, dans failure_log, le log qui montre le problème.

Exemple : une base de démo par prospect

Sur une branche en mode SaaS, chaque base est une instance Odoo à part, avec sa propre adresse. Un bouton dans votre CRM peut créer une base pour un prospect, la remplir de données de démo adaptées, puis la supprimer après la démo.

Créez la base (Lecture et écriture). Le nom devient son adresse et doit être unique, ajoutez donc un court suffixe aléatoire :
```
curl -s -X POST -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "acme-demo-x7k2", "lang": "fr_FR", "admin_password": "un-long-mot-de-passe-aleatoire"}' \
  "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/databases"
```
La réponse contient un id, l'url de la base (par exemple https://acme-demo-x7k2.skysize.io) et "pending": true.
Interrogez GET .../databases/{id} avec cet id jusqu'à ce que pending disparaisse. En cas de succès, vous obtenez la base. Si la création a échoué, la réponse contient "failed": true et un failure_reason :
- db_name_taken : quelqu'un a pris le nom entre-temps. Choisissez-en un autre.
- create_failed : réessayez, et contactez le support si l'échec se répète.
- cancelled : la création a été annulée.
Remplissez-la avec l'API externe d'Odoo (XML-RPC ou JSON-RPC) à cette url, en vous connectant en tant qu'admin avec le mot de passe choisi : installez les applications de la démo, puis créez les clients, les produits et les commandes qui correspondent au prospect.
Après la démo, supprimez-la (Complet) : DELETE .../databases/{database_id}. Une dernière sauvegarde est faite avant la suppression de la base.

Chaque base de démo tourne dans le conteneur de la branche et utilise ses workers et son stockage : supprimez celles dont vous n'avez plus besoin.

Créer un jeton d'API​

Envoyer une requête​

Ce que couvre l'API​

Suivre un log en direct​

Exemple : relancer un build après un merge​

Exemple : une base de démo par prospect​