Introduction à l'API

L’API de Host reprend le sous-ensemble de l’API Vercel qu’utilise la CLI pour relier un dossier, construire et déployer. Elle accepte du JSON, renvoie du JSON, et s’authentifie par une clé d’API.

Utilise l’API si tu écris ton propre outil. Pour déployer depuis un poste ou une CI, la CLI suffit.

Adresse de base

https://api.host.hgdc.ch

Toutes les requêtes passent en HTTPS.

Authentification

Envoie ta clé dans l’en-tête Authorization. Les clés commencent par ah_ et se créent dans l’onglet Clés d’API de l’organisation. Voir Créer et révoquer une clé d’API.

Authorization: Bearer ah_…

curl https://api.host.hgdc.ch/v2/user \
  -H "Authorization: Bearer $VERCEL_TOKEN"

Il existe deux sortes de clés :

Clé	Portée	Variables sensibles
Clé d’organisation, créée par un admin ou un propriétaire	Tous les projets de l’organisation, création de projets comprise	Jamais renvoyées
Clé de projet, posée par l’app GitHub dans le dépôt	Ce seul projet. Tout autre projet répond 404	Renvoyées, pour le build

Une clé donne accès aux variables d’environnement de tes projets. Garde-la dans un gestionnaire de secrets, jamais dans le code ni dans le navigateur.

L’organisation vient de la clé

Chaque clé appartient à une organisation, et chaque requête s’exécute dans cette organisation. Un identifiant d’organisation dans l’URL, ou un paramètre teamId ou slug, que la CLI ajoute parfois, est ignoré.

Versions dans le chemin

Les chemins gardent les numéros de version de l’API Vercel, comme /v2, /v9 ou /v13, pour que la CLI fonctionne sans modification. Plusieurs versions d’un même endpoint renvoient la même réponse : /v9/projects et /v10/projects par exemple.

Pagination

Les listes ne sont pas paginées. Elles renvoient un objet pagination pour la compatibilité, avec next toujours à null.

Limites de débit

Chaque clé dispose de 600 requêtes par minute, avec des rafales de 120. L’envoi de fichiers a son propre budget : 6 000 par minute, avec des rafales de 3 000.

Au-delà, l’API répond 429 avec le code rate_limited :

{
  "error": {
    "code": "rate_limited",
    "message": "Trop de requêtes, réessaie dans un instant."
  }
}

La réponse porte un en-tête retry-after quand l’attente est connue. La création de déploiements est aussi limitée par organisation : voir Limites.

Endpoints

Méthode	Chemin	Rôle
GET	/v2/user	Personne qui a créé la clé
GET	/v2/teams	Organisation de la clé
GET	/v2/teams/:idOrSlug	Lire l’organisation
GET	/v9/projects	Lister les projets
GET	/v9/projects/:idOrName	Lire un projet
POST	/v11/projects	Créer un projet
POST	/v2/files	Envoyer un fichier
POST	/v13/deployments	Créer un déploiement
GET	/v13/deployments/:id	Lire un déploiement
GET	/v3/deployments/:id/events	Suivre les logs
GET	/v3/env/pull/:project/:target	Lire les variables d’un environnement

Les erreurs et leurs codes sont sur Erreurs.