Docs/ Référence API/ Démarrage rapide

Démarrage rapide API

Faites votre premier appel à l’API de sh0 en quelques minutes : créez une clé d’API, listez vos apps, redéployez-en une et lisez les formats de réponse.

Note

L’API est servie par votre panneau sh0, sur son domaine une fois que vous en avez posé un, sinon sur le port 9000 du serveur. Chaque chemin commence par /api/v1. Les exemples utilisent https://panel.example.com : remplacez-le par votre propre adresse.

Créer une clé d’API

Dans le tableau de bord, ouvrez Paramètres → Clés API, créez une clé au niveau d’accès dont vous avez besoin et copiez-la : elle n’est affichée qu’une fois. Les niveaux d’accès sont expliqués dans Authentification de l’API. Gardez-la ensuite dans une variable d’environnement :

Terminal

export SH0_TOKEN="sh0_..."

Warning

Traitez la clé comme un mot de passe : gardez-la dans un coffre à secrets ou une variable d'environnement, jamais dans un dépôt. Révoquez-la depuis Paramètres → Clés API dès qu'elle a pu fuir.

Étape 2 : Lister vos apps

Listez vos applications. Tous les niveaux d’accès le permettent :

Terminal

curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Redéployer une app

Déclenchez un nouveau déploiement d’une app existante, avec son identifiant tiré de la liste. Il faut le niveau Déploiement ou Administration. Le corps peut être vide, mais il doit être du JSON valide :

Terminal

curl -X POST https://panel.example.com/api/v1/apps/APP_ID/deployments \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Pour créer une app à partir de votre propre code, le chemin le plus court est la CLI : sh0 push envoie le répertoire de votre projet sous forme d’archive et le déploie, avec ou sans Dockerfile.

Format de réponse

Toutes les réponses de l'API sh0 suivent un format cohérent :

Réponses réussies :

Success Format

{
  "data": { ... }
}

Réponses de liste avec pagination :

List Format

{
  "data": [ ... ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Réponses d'erreur :

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "App with id 'app_xyz' not found"
  }
}

Pagination

Les endpoints de liste supportent la pagination avec deux paramètres de requête :

Paramètre	Défaut	Description
`page`	1	Numéro de page (indexé à partir de 1)
`per_page`	20	Éléments par page (max 100)

Terminal

# Get page 2, 50 items per page
curl "https://panel.example.com/api/v1/apps/APP_ID/deployments?page=2&per_page=50" \
  -H "Authorization: Bearer $SH0_TOKEN"

Gestion des erreurs

L'API utilise des codes de statut HTTP standard. Voici les plus courants :

Statut	Signification
200	Succès
201	Ressource créée
400	Requête invalide (paramètres incorrects)
401	Non autorisé (jeton manquant ou invalide)
403	Interdit (permissions insuffisantes)
404	Ressource non trouvée
409	Conflit (nom en double, etc.)
422	Erreur de validation
429	Limitation de débit
500	Erreur interne du serveur

Tip

Vérifiez toujours le champ error.code pour la gestion programmatique des erreurs plutôt que d'analyser la chaîne du message, qui peut changer entre les versions.

Étapes suivantes

Maintenant que vous pouvez vous authentifier et effectuer des appels API de base, explorez toutes les capacités de l'API sh0 :

Référence API complète -- Explorateur interactif avec les 180+ endpoints
Déploiement Git -- Configurer des workflows de déploiement par push
Mise à l'échelle -- Mettre à l'échelle les apps via l'API
Surveillance -- Récupérer les métriques et les données de santé

Explorateur API sh0 montrant les catégories d'endpoints disponibles

Authentification de l'API

Référence complète