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

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": "<h1>Bonjour</h1>" }
    ]
  }'

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<string, string>	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.

curl https://api.host.hgdc.ch/v13/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z \
  -H "Authorization: Bearer $VERCEL_TOKEN"

Réponse 200 :

{
  "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://app.hgdc.ch/host/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 (<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.

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 :

{"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 :

{"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é

GET /v6/deployments

Liste les déploiements, du plus récent au plus ancien. Portée host:read. Paramètres : projectId (id ou nom), target (production ou preview), limit (20 par défaut, 100 au plus), until (valeur pagination.next de la page précédente). C’est ce que lit vercel ls.

POST /v10/projects/:p/promote/:id

Met en production un déploiement prêt du projet, sans rien reconstruire. Portée host:deploy. Répond 201 : la mise en production est déjà faite. C’est ce que fait vercel promote.

POST /v9/projects/:p/rollback/:id

Remet en production un ancien déploiement de production prêt. Portée host:deploy. Répond 201, ou 400 si ce déploiement est déjà en production. C’est ce que fait vercel rollback.

Pour ces deux routes, :id est l’identifiant du déploiement ou son adresse (site-atelier-x1y2z3.hgdc.cloud, comme l’affiche vercel ls). Une clé de projet, posée dans un dépôt, ne peut ni promouvoir ni revenir en arrière : elle reçoit 403.

PATCH /v12/deployments/:id/cancel

Annule un build en file ou en cours. Portée host:deploy. Répond le déploiement, à l’état CANCELED.

DELETE /v13/deployments/:id

Supprime un déploiement avant sa date d’effacement. Portée host:deploy. C’est ce que fait vercel rm. :id est l’identifiant du déploiement ou son adresse. La route accepte aussi ?url=<adresse>, comme chez Vercel.

curl -X DELETE https://api.host.hgdc.ch/v13/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z \
  -H "Authorization: Bearer $VERCEL_TOKEN"

Réponse 200 :

{ "uid": "jd7f2k9m3x8q1p5s6t4v0w7y2z", "state": "DELETED" }

Le déploiement disparaît avec ses fichiers et ses logs de build. Son adresse répond ensuite 410. La suppression ne se défait pas. Les durées automatiques sont décrites sur Déploiements.

Statut	Cause
400	Déploiement en production en ligne : mets une autre version en production d’abord (promote ou rollback). Ou build en file ou en cours : annule-le d’abord, avec PATCH /v12/deployments/:id/cancel
403	Clé de projet posée dans un dépôt : elle ne supprime rien
404	Déploiement introuvable, d’une autre organisation, ou hors de la portée de la clé

GET /now/deployments/:id/aliases

Liste les adresses rattachées à un déploiement. C’est la lecture que fait vercel rm avant de supprimer.

{ "aliases": ["site-atelier.hgdc.cloud"] }

Ce que Host ne fait pas

• vercel logs (journaux d’exécution) n’est pas pris en charge. Le journal de build se lit avec vercel inspect --logs.