# GET /races/{id}/editions

> Version générique : tous les champs sont listés avec la formule minimale qui y donne accès (`FREE`, `PRO`, `PARTNER`). Envoyez votre clé API (`Authorization: Bearer th_live_…`) ou connectez-vous à votre espace développeur pour obtenir la version personnalisée.

`GET https://dev.trailhorizon.fr/api/v1/races/{id}/editions`

> Endpoint réservé aux formules `PARTNER`. Un compte qui n'y a pas droit reçoit `403 forbidden`.

Historique des éditions par année et par format. Les formats archivés et les éditions brouillon (non confirmées) sont exclus ; années les plus récentes d'abord.

## Paramètres

| Paramètre | Emplacement | Type | Requis | Description |
| --- | --- | --- | --- | --- |
| `id` | chemin | string | oui | Identifiant de la course (`id`). |

## Réponse `200`

Chaque clé n'est présente que si le champ correspondant est autorisé pour votre compte (`formatId` et `name` : `formats.id`, `formats.name` ; `startAt`, `distance`, `elevation`, `price`, `currency` : champs `formats.*` du même nom). `status` est toujours présent.

```json
{
  "data": {
    "raceId": "clx1a2b3c0000abcd1234efgh",
    "editions": [
      {
        "edition": "2027",
        "year": 2027,
        "formats": [
          {
            "formatId": "clx9z8y7x0001abcd5678ijkl",
            "name": "Le Grand Tour",
            "status": "CONFIRMED",
            "startAt": "2027-06-12T05:00:00.000Z",
            "distance": 52.4,
            "elevation": 3100,
            "price": 85,
            "currency": "EUR"
          },
          {
            "formatId": "clx9z8y7x0002abcd5678mnop",
            "name": "La Petite Boucle",
            "status": "CONFIRMED",
            "startAt": "2027-06-12T08:30:00.000Z",
            "distance": 21.2,
            "elevation": 1100,
            "price": 38,
            "currency": "EUR"
          }
        ]
      },
      {
        "edition": "2026",
        "year": 2026,
        "formats": [
          {
            "formatId": "clx9z8y7x0001abcd5678ijkl",
            "name": "Le Grand Tour",
            "status": "DONE",
            "startAt": "2026-06-13T05:00:00.000Z",
            "distance": 51.8,
            "elevation": 3050,
            "price": 80,
            "currency": "EUR"
          }
        ]
      }
    ]
  }
}
```

## Exemple

```bash
curl -H "Authorization: Bearer th_live_VOTRE_CLE" \
  "https://dev.trailhorizon.fr/api/v1/races/clx1a2b3c0000abcd1234efgh/editions"
```

## Erreurs

| Statut | Code | Signification |
| --- | --- | --- |
| 401 | `missing_api_key` | Header `Authorization` absent. |
| 401 | `invalid_api_key` | Clé mal formée ou inconnue. |
| 401 | `api_key_revoked` | Clé révoquée. |
| 403 | `account_suspended` / `account_revoked` | Compte suspendu ou révoqué. |
| 403 | `tos_not_accepted` / `tos_outdated` | Conditions d'utilisation de l'API non acceptées, ou à accepter de nouveau. |
| 403 | `forbidden` | L'historique des éditions n'est pas disponible pour votre formule. |
| 404 | `not_found` | Course inconnue, non publiée ou masquée. |
| 429 | `rate_limit_exceeded` | Trop de requêtes dans la minute. Voir `Retry-After`. |
| 429 | `daily_quota_exceeded` | Quota journalier atteint. Voir `Retry-After`. |
| 500 | `internal_error` | Erreur interne. |