# Déploiements
Un déploiement est une version figée de ton site, avec sa propre adresse. Créer un déploiement est l’appel central de `vercel deploy`.
## Déroulement d’une création
1. Envoie la liste des fichiers avec leur empreinte SHA1.
2. Si des fichiers manquent, l’API répond `400 missing_files`, avec leurs empreintes dans `missing`. Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/).
3. Renvoie exactement la même requête. Elle crée le déploiement.
Les petits fichiers peuvent aussi être inclus directement dans le corps, dans le champ `data`, sans passer par `/v2/files`. La limite de 20 Mo vaut alors pour l’ensemble des fichiers inclus.
## POST `/v13/deployments`
```bash
curl -X POST https://api.host.hgdc.ch/v13/deployments \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "site-atelier",
"target": "production",
"files": [
{ "file": "index.html", "data": "Bonjour
" }
]
}'
```
### Corps
| Champ | Type | Requis | Description |
| --------------------------- | ------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | Si `project` est absent | Nom du projet. Le projet est créé s’il n’existe pas |
| `project` | `string` | Non | Identifiant ou nom du projet. Prioritaire sur `name` |
| `target` | `"production"` ou `null` | Non | `production` pour la production. Toute autre valeur crée une preview |
| `files` | `object[]` | Oui | Fichiers du déploiement, 15 000 au plus. Voir ci-dessous |
| `projectSettings.framework` | `string` ou `null` | Non | Framework, enregistré si le déploiement crée le projet |
| `gitMetadata` | `object` | Non | `commitRef` (branche), `commitSha` et `commitMessage`, affichés dans la console |
| `meta` | `Record` | Non | Métadonnées libres. `githubCommitRef`, `githubCommitSha` et `githubCommitMessage` remplacent `gitMetadata` quand il manque |
Chaque élément de `files` prend l’une de ces formes :
- `{ "file", "sha", "size" }` : chemin relatif, empreinte SHA1 et taille en octets, pour un fichier déjà envoyé par `/v2/files` ;
- `{ "file", "data", "encoding" }` : contenu inclus. `encoding` vaut `utf-8` (par défaut) ou `base64`.
`mode` (permissions Unix) est accepté et conservé. Un dossier vide, `{ "file", "mode" }`, est ignoré.
### Réponse
Réponse `200` : l’objet déploiement. Le déploiement naît le plus souvent à l’état `QUEUED`. Suis-le avec `GET /v13/deployments/:id`, plus bas sur cette page, ou avec le flux de logs `GET /v3/deployments/:id/events`.
### Erreurs
| Statut | Code | Cause |
| ------ | ------------------- | ------------------------------------------------------------------ |
| `400` | `bad_request` | Corps invalide, ou nom de projet absent. Le message nomme le champ |
| `400` | `missing_files` | Des fichiers sont à envoyer avant de créer le déploiement |
| `403` | `forbidden` | La clé est limitée à un autre projet |
| `409` | `deployment_closed` | Le déploiement a été annulé ou a échoué : rien n’est publié |
| `413` | `payload_too_large` | Les fichiers inclus dépassent 20 Mo au total |
## GET `/v13/deployments/:id`
Lit un déploiement.
```bash
curl https://api.host.hgdc.ch/v13/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z \
-H "Authorization: Bearer $VERCEL_TOKEN"
```
Réponse `200` :
```json
{
"id": "jd7f2k9m3x8q1p5s6t4v0w7y2z",
"uid": "jd7f2k9m3x8q1p5s6t4v0w7y2z",
"url": "site-atelier-h3k9x2.hgdc.cloud",
"name": "site-atelier",
"projectId": "j97d3k2m8x1q4p6s7t9v0w2y5z",
"ownerId": "k57a1b2c3d4e5f6g7h8j9k0m1n",
"readyState": "READY",
"status": "READY",
"target": "production",
"type": "LAMBDAS",
"createdAt": 1760259600000,
"buildingAt": 1760259601000,
"ready": 1760259604000,
"alias": ["site-atelier.hgdc.cloud"],
"aliasAssigned": true,
"aliasAssignedAt": 1760259604000,
"aliasError": null,
"errorMessage": null,
"inspectorUrl": "https://host.hgdc.ch/atelier/site-atelier/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z",
"meta": {
"branch": "main",
"commitSha": "4c3e2f1a9b8d7c6e5f4a3b2c1d0e9f8a7b6c5d4e",
"commitMessage": "Nouvelle page Tarifs"
},
"creator": { "uid": "u1a2b3c4d5" }
}
```
| Champ | Type | Description |
| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Identifiant du déploiement. `uid` porte la même valeur |
| `url` | `string` | Adresse du déploiement, sans `https://`. Elle reste valable tant que le déploiement existe |
| `name` | `string` | Nom du projet |
| `projectId` | `string` | Identifiant du projet |
| `ownerId` | `string` | Identifiant de l’organisation |
| `readyState` | `string` | État : `QUEUED`, `BUILDING`, `READY`, `ERROR` ou `CANCELED`. `status` porte la même valeur |
| `target` | `"production"` ou `null` | `production`, ou `null` pour une preview |
| `createdAt` | `number` | Date de création, en millisecondes |
| `buildingAt` | `number` | Début du traitement, en millisecondes |
| `ready` | `number` ou `null` | Fin du traitement. `null` tant que le déploiement n’est pas prêt |
| `alias` | `string[]` | Adresse de production du projet (`.hgdc.cloud`), une fois un déploiement de production prêt. Vide pour une preview. La CLI l’affiche sur la ligne « Aliased » |
| `aliasAssigned` | `boolean` | `true` quand le déploiement est prêt |
| `aliasAssignedAt` | `number` ou `null` | Moment où l’adresse de production lui a été attribuée. `null` pour une preview |
| `aliasError` | `null` | Toujours `null` |
| `errorMessage` | `string` ou `null` | Cause de l’échec, quand `readyState` vaut `ERROR` |
| `inspectorUrl` | `string` | Page du déploiement dans la console |
| `type` | `"LAMBDAS"` | Valeur fixe, pour la CLI |
| `meta` | `object` | Informations Git connues : `branch`, `commitSha`, `commitMessage` |
| `creator.uid` | `string` | Personne qui a créé la clé utilisée |
### Attendre la fin
Pour attendre qu’un déploiement soit prêt, interroge cet endpoint toutes les secondes jusqu’à `READY`, `ERROR` ou `CANCELED`. Tu peux aussi ouvrir le flux `GET /v3/deployments/:id/events` décrit plus bas, qui se ferme tout seul à la fin.
| Erreur | Code | Cause |
| ------ | ----------- | ----------------------------------------------------------------------------- |
| `404` | `not_found` | Déploiement inconnu, d’une autre organisation, ou hors de la portée de la clé |
## GET `/v3/deployments/:id/events`
Renvoie les logs de build d’un déploiement, un événement JSON par ligne (NDJSON). Avec `follow=1`, la connexion reste ouverte et reçoit les nouvelles lignes au fil de l’eau.
```bash
curl -N "https://api.host.hgdc.ch/v3/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z/events?follow=1" \
-H "Authorization: Bearer $VERCEL_TOKEN"
```
| Paramètre | Valeur | Rôle |
| --------- | ------ | --------------------------------------------------------------------------- |
| `follow` | `1` | Garde la connexion ouverte jusqu’à la fin du déploiement, 9 minutes au plus |
Le type de réponse est `application/x-ndjson`. Chaque ligne de log ressemble à ceci :
```json
{"type":"stdout","created":1760259601000,"date":1760259601000,"deploymentId":"jd7f2k9m3x8q1p5s6t4v0w7y2z","id":"l3k…","text":"Publication de 42 fichiers","payload":{"id":"l3k…","text":"Publication de 42 fichiers","date":1760259601000,"deploymentId":"jd7f2k9m3x8q1p5s6t4v0w7y2z"}}
```
| Champ | Type | Description |
| --------- | ------------------------ | ------------------------------------------------------------------ |
| `type` | `"stdout"` ou `"stderr"` | `stderr` pour une ligne d’erreur |
| `text` | `string` | Texte de la ligne |
| `date` | `number` | Date de la ligne, en millisecondes. `created` porte la même valeur |
| `payload` | `object` | Les mêmes champs, au format historique de la CLI |
Une fois le déploiement terminé, une dernière ligne donne son état, puis le flux se ferme :
```json
{"type":"state","event":"state","date":1760259604000,"payload":{"value":"READY"}}
```
Les lignes du build GitHub Actions ne sont pas renvoyées ici : elles sont dans le run GitHub, et la console les affiche sur la page du déploiement.
Le même endpoint répond aussi sous `/v3/now/deployments/:id/events`.
| Erreur | Code | Cause |
| ------ | ----------- | --------------------------------------------------- |
| `404` | `not_found` | Déploiement inconnu, ou hors de la portée de la clé |