# 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](/host/docs/reference/cli/) suffit. ## Adresse de base ```text 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](/host/docs/guides/cle-d-api/). Les anciennes clés `ah_…` restent acceptées. ```http Authorization: Bearer hgdc_host_… ``` ```bash 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 | > **Attention** > > 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 : ```text 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` : ```json { "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](/host/docs/reference/limites/). ## Endpoints | Méthode | Chemin | Rôle | | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------- | | `GET` | [`/v2/user`](/host/docs/reference/api/utilisateur/) | Personne qui a créé la clé | | `GET` | [`/v2/teams`](/host/docs/reference/api/utilisateur/) | Organisation de la clé | | `GET` | [`/v2/teams/:idOrSlug`](/host/docs/reference/api/utilisateur/) | Lire l’organisation | | `GET` | [`/v9/projects`](/host/docs/reference/api/projets/) | Lister les projets | | `GET` | [`/v9/projects/:idOrName`](/host/docs/reference/api/projets/) | Lire un projet | | `PATCH` | [`/v9/projects/:id`](/host/docs/reference/api/projets/) | Changer la durée de conservation des déploiements | | `POST` | [`/v11/projects`](/host/docs/reference/api/projets/) | Créer un projet | | `POST` | [`/v2/files`](/host/docs/reference/api/fichiers/) | Envoyer un fichier | | `POST` | [`/v13/deployments`](/host/docs/reference/api/deploiements/) | Créer un déploiement | | `GET` `DELETE` | [`/v13/deployments/:id`](/host/docs/reference/api/deploiements/) | Lire, supprimer un déploiement | | `GET` | [`/now/deployments/:id/aliases`](/host/docs/reference/api/deploiements/) | Lister les adresses d’un déploiement | | `GET` | [`/v3/deployments/:id/events`](/host/docs/reference/api/deploiements/) | Suivre les logs | | `GET` | [`/v6/deployments`](/host/docs/reference/api/deploiements/) | Lister les déploiements | | `POST` | [`/v10/projects/:p/promote/:id`](/host/docs/reference/api/deploiements/) | Mettre en production | | `POST` | [`/v9/projects/:p/rollback/:id`](/host/docs/reference/api/deploiements/) | Revenir en arrière | | `PATCH` | [`/v12/deployments/:id/cancel`](/host/docs/reference/api/deploiements/) | Annuler un build | | `GET` | [`/v3/env/pull/:project/:target`](/host/docs/reference/api/variables/) | Lire les variables d’un environnement | | `GET` `POST` | [`/v10/projects/:p/env`](/host/docs/reference/api/variables/) | Lister, créer des variables | | `PATCH` `DELETE` | [`/v10/projects/:p/env/:id`](/host/docs/reference/api/variables/) | Modifier, supprimer une variable | | `GET` `POST` | [`/v10/projects/:p/domains`](/host/docs/reference/api/domaines/) | Lister, ajouter des domaines | | `GET` `DELETE` | [`/v9/projects/:p/domains/:domain`](/host/docs/reference/api/domaines/) | Lire, retirer un domaine | | `POST` | [`/v9/projects/:p/domains/:domain/verify`](/host/docs/reference/api/domaines/) | Vérifier un domaine | Les erreurs et leurs codes sont sur [Erreurs](/host/docs/reference/api/erreurs/).