# Projets

Un projet correspond à un site. Il a ses variables, ses domaines et son historique de déploiements.

## GET `/v9/projects`

Liste les projets de l’organisation. Avec une clé de projet, la liste ne contient que ce projet. La liste compte 100 projets au plus.

```bash
curl https://api.host.hgdc.ch/v9/projects \
  -H "Authorization: Bearer $VERCEL_TOKEN"
```

Réponse `200` :

```json
{
  "projects": [
    {
      "id": "j97d3k2m8x1q4p6s7t9v0w2y5z",
      "name": "site-atelier",
      "accountId": "k57a1b2c3d4e5f6g7h8j9k0m1n",
      "framework": "astro",
      "rootDirectory": null,
      "buildCommand": null,
      "installCommand": null,
      "outputDirectory": null,
      "nodeVersion": "24.x",
      "createdAt": 1760259600000,
      "updatedAt": 1760259600000
    }
  ],
  "pagination": { "count": 1, "next": null, "prev": null }
}
```

Le même endpoint répond aussi sous `/v10/projects`.

## GET `/v9/projects/:idOrName`

Lit un projet, par son identifiant ou son nom, sans tenir compte de la casse.

```bash
curl https://api.host.hgdc.ch/v9/projects/site-atelier \
  -H "Authorization: Bearer $VERCEL_TOKEN"
```

Réponse `200` : l’objet projet, décrit ci-dessous. Les routes `/v9` et `/v10` renvoient la même réponse.

| Erreur | Code        | Cause                                                                             |
| ------ | ----------- | --------------------------------------------------------------------------------- |
| `404`  | `not_found` | Aucun projet de ce nom dans l’organisation, ou projet hors de la portée de la clé |

## POST `/v11/projects`

Crée un projet. Tu peux aussi t’en passer : le premier déploiement sur un nom inconnu crée le projet.

```bash
curl -X POST https://api.host.hgdc.ch/v11/projects \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"site-atelier","framework":"astro"}'
```

| Champ       | Type               | Requis | Description                                                                                                                                        |
| ----------- | ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | `string`           | Oui    | Nom du projet, 100 caractères au plus. Il devient le nom dans l’URL, en minuscules                                                                 |
| `framework` | `string` ou `null` | Non    | `nextjs`, `astro`, `vite`, `sveltekit`, `nuxt`, `tanstack-start` ou `react-router`. Une autre valeur, ou `null`, enregistre un site sans framework |

Réponse `200` : l’objet projet créé.

| Erreur | Code          | Cause                                              |
| ------ | ------------- | -------------------------------------------------- |
| `400`  | `bad_request` | Nom absent ou trop long                            |
| `403`  | `forbidden`   | La clé est limitée à un projet : elle ne crée rien |
| `409`  | `conflict`    | Un projet porte déjà ce nom                        |

## L’objet projet

| Champ                | Type                 | Description                                                                                                                                                                                                                                                            |
| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | `string`             | Identifiant du projet. C’est la valeur de `VERCEL_PROJECT_ID`                                                                                                                                                                                                          |
| `name`               | `string`             | Nom du projet, dans l’URL de la console                                                                                                                                                                                                                                |
| `accountId`          | `string`             | Identifiant de l’organisation propriétaire                                                                                                                                                                                                                             |
| `framework`          | `string` ou `null`   | Framework enregistré, ou `null` pour un site sans framework                                                                                                                                                                                                            |
| `rootDirectory`      | `string` ou `null`   | Dossier de l’app dans le dépôt, pour un monorepo                                                                                                                                                                                                                       |
| `buildCommand`       | `string` ou `null`   | Commande de build imposée. `null` : celle détectée par `vercel build`                                                                                                                                                                                                  |
| `installCommand`     | `string` ou `null`   | Commande d’installation imposée                                                                                                                                                                                                                                        |
| `outputDirectory`    | `string` ou `null`   | Dossier de sortie imposé                                                                                                                                                                                                                                               |
| `nodeVersion`        | `"22.x"` ou `"24.x"` | Version de Node.js du build                                                                                                                                                                                                                                            |
| `createdAt`          | `number`             | Date de création, en millisecondes depuis l’époque Unix                                                                                                                                                                                                                |
| `updatedAt`          | `number`             | Même valeur que `createdAt`                                                                                                                                                                                                                                            |
| `link`               | `object`             | Présent seulement pour un projet relié à GitHub : `type` (`github`), `repo` (`propriétaire/dépôt`) et `productionBranch`                                                                                                                                               |
| `alias`              | `object[]`           | Adresse de production du projet : `domain` (`<projet>.hgdc.cloud`), `target` (`PRODUCTION`), `environment` (`production`), `createdAt`, `deployment` (`null`). Les domaines personnalisés n’y figurent pas                                                             |
| `targets.production` | `object`             | Présent une fois une production en ligne : le déploiement servi, avec `id`, `url`, `alias` (`["<projet>.hgdc.cloud"]`), `aliasAssigned` (moment de la mise en ligne), `readyState`, `createdAt`, `readyAt` et `meta`. `targets` vaut `{}` avant la première production |

Pour un projet dont le framework n’est pas reconnu, `framework` vaut `null`.

## Voir aussi

- [Déploiements](/docs/reference/api/deploiements/) : créer un déploiement pour ce projet.
- [Erreurs](/docs/reference/api/erreurs/) : la liste des codes.