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 hgdc_host_ et se créent dans l’onglet Clés d’API de l’organisation, avec leurs portées et leur durée. Voir Créer et révoquer une clé d’API. Les anciennes clés ah_… restent acceptées.

Authorization: Bearer hgdc_host_…

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.

Chaque route demande une portée (host:read, host:deploy, host:env_read, host:env_write, host:domains ou host:write). Une portée qui manque répond 403 avec le code forbidden et le nom de la portée. La description OpenAPI des routes et de leurs portées est publique :

https://api.host.hgdc.ch/openapi.json

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

La liste des déploiements (/v6/deployments) se pagine comme chez Vercel : limit, puis until avec la valeur pagination.next de la page précédente. Les autres listes ne sont pas paginées : next y vaut 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.

Les clés refusées sont aussi limitées, par adresse IP : après 20 clés inconnues, expirées ou révoquées en 10 minutes, l’API répond 429 au lieu de 403 jusqu’à la fin de la fenêtre. Une clé valide n’est jamais bloquée, même depuis cette adresse. Le serveur MCP suit la même règle.

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
PATCH	/v9/projects/:id	Changer la durée de conservation des déploiements
POST	/v11/projects	Créer un projet
POST	/v2/files	Envoyer un fichier
POST	/v13/deployments	Créer un déploiement
GET DELETE	/v13/deployments/:id	Lire, supprimer un déploiement
GET	/now/deployments/:id/aliases	Lister les adresses d’un déploiement
GET	/v3/deployments/:id/events	Suivre les logs
GET	/v6/deployments	Lister les déploiements
POST	/v10/projects/:p/promote/:id	Mettre en production
POST	/v9/projects/:p/rollback/:id	Revenir en arrière
PATCH	/v12/deployments/:id/cancel	Annuler un build
GET	/v3/env/pull/:project/:target	Lire les variables d’un environnement
GET POST	/v10/projects/:p/env	Lister, créer des variables
PATCH DELETE	/v10/projects/:p/env/:id	Modifier, supprimer une variable
GET POST	/v10/projects/:p/domains	Lister, ajouter des domaines
GET DELETE	/v9/projects/:p/domains/:domain	Lire, retirer un domaine
POST	/v9/projects/:p/domains/:domain/verify	Vérifier un domaine

Les erreurs et leurs codes sont sur Erreurs.