Aller au contenu
FREN

Versions de l’API

Votre intégration ne casse pas lorsque Cord évolue : chaque clé et chaque endpoint de webhook restent sur la version avec laquelle ils ont été créés.

Version en vigueur

La version en vigueur est 2026-10-01. C’est aussi la seule : la version de base qui a fixé la forme de l’API lorsque Cord a commencé à la versionner. Chaque version porte la date de sa publication.

Version Changements
2026-10-01 Version de base : la forme de l’API au moment où le versionnement a été mis en place.

Comment la version d’une requête est choisie

Cord détermine la version de chaque requête à /api/v1 dans cet ordre :

  1. L’en-tête Cord-Version de la requête, si vous l’envoyez.
  2. La version fixée de la clé. Chaque clé est fixée sur la version en vigueur le jour de sa création. Renouveler une clé conserve la version de la précédente.
  3. La version de base (2026-10-01), pour les clés créées avant l’existence du versionnement.

Cord produit chaque réponse dans sa forme la plus récente et la convertit, changement par changement, vers la version déterminée. Chaque réponse comporte l’en-tête Cord-Version avec la version utilisée pour répondre.

curl -i https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_test_..." \
  -H "Cord-Version: 2026-10-01"
HTTP/2 200
content-type: application/json
cord-request-id: req_3f9c2a1b7d4e6f8a0b1c2d3e
cord-version: 2026-10-01

Il n’est pas possible pour l’instant de changer la version fixée d’une clé existante. Pour passer à une nouvelle version, envoyez l’en-tête Cord-Version dans vos requêtes ou créez une nouvelle clé.

Dans les SDK et la CLI

Les clients officiels envoient toujours la version avec laquelle ils ont été construits : une mise à jour de Cord ne change donc pas ce qu’ils lisent.

Client Version envoyée Comment la changer
@flouviahq/node CORD_API_VERSION (2026-10-01) new Cord(sk, { apiVersion: '2026-10-01' })
@flouviahq/elements CORD_API_VERSION (2026-10-01) Elle se met à jour avec le paquet.
@flouviahq/cli 2026-10-01 Elle se met à jour avec le paquet. 
import { Cord, CORD_API_VERSION } from '@flouviahq/node';

const cord = new Cord(process.env.CORD_SECRET_KEY!, { apiVersion: CORD_API_VERSION });

Webhooks

Chaque endpoint de webhook est fixé sur la version en vigueur le jour de sa création, que ce soit depuis le Workbench, par POST /api/v1/webhooks ou avec une session cord listen. Le data de chaque envoi est converti vers la version de cet endpoint, et non vers celle de la clé qui a provoqué l’événement. Si vous avez deux endpoints sur des versions différentes, tous deux reçoivent le même événement, avec le même id, chacun dans sa forme.

Les envois ne comportent pas l’en-tête Cord-Version, et aucun en-tête ne permet de demander une autre version par envoi : pour recevoir une autre forme, créez un nouvel endpoint.

Version non valide

Une version qui n’existe pas répond 400 avec code: "invalid_api_version". Cord ne bascule jamais en silence vers une autre version. Le message liste les versions disponibles :

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_test_..." \
  -H "Cord-Version: 2025-01-01"
{
  "error": "Cord-Version \"2025-01-01\" no existe. Versiones disponibles: 2026-10-01.",
  "code": "invalid_api_version",
  "request_id": "req_8a1c4e7b2d9f3a6c0e5b8d1f",
  "doc_url": "https://docs.cordhq.app/docs/desarrolladores/esenciales/errores#invalid_api_version"
}

Le format compte aussi : Cord-Version: 2026-10 ou latest renvoient la même erreur.

Politique de changements

Exige une nouvelle version (n’atteint jamais votre intégration sans que vous la demandiez) :

  • supprimer ou renommer un champ d’une réponse ou d’un webhook ;
  • changer le type ou la signification d’un champ ;
  • changer un code d’erreur.

Arrive sans nouvelle version, car cela ne casse pas une intégration bien écrite :

  • de nouveaux champs dans une réponse ou dans le data d’un webhook ;
  • de nouveaux types d’événements ;
  • de nouveaux endpoints et de nouveaux paramètres facultatifs.

Le texte du champ error est un message destiné aux personnes et peut être amélioré à tout moment : programmez sur code, jamais sur le texte.

Votre intégration doit ignorer les champs qu’elle ne connaît pas et traiter un type d’événement inconnu comme quelque chose qu’elle peut écarter. Si vous avez laissé les événements d’un endpoint non cochés, vous les recevez tous, y compris ceux que Cord ajoutera plus tard.

Lorsqu’une nouvelle version existera, elle apparaîtra dans le tableau ci-dessus avec ce qui a changé.