# 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](/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 `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](/docs/guides/cle-d-api/).

```http
Authorization: Bearer ah_…
```

```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.

## 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` :

```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](/docs/reference/limites/).

## Endpoints

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

Les erreurs et leurs codes sont sur [Erreurs](/docs/reference/api/erreurs/).