Zum Inhalt springen
DEEN

API-Versionen

Ihre Integration bricht nicht, wenn sich Cord ändert: Jeder Schlüssel und jeder Webhook-Endpoint bleibt auf der Version, mit der er erstellt wurde.

Aktuelle Version

Die aktuelle Version ist 2026-10-01. Sie ist zugleich die einzige: die Basisversion, die die Form der API festgelegt hat, als Cord mit der Versionierung begann. Jede Version wird nach dem Datum ihrer Veröffentlichung benannt.

Version Änderungen
2026-10-01 Basisversion: die Form der API zum Zeitpunkt der Einführung der Versionierung.

Wie die Version einer Anfrage gewählt wird

Cord ermittelt die Version jeder Anfrage an /api/v1 in dieser Reihenfolge:

  1. Der Header Cord-Version der Anfrage, wenn Sie ihn senden.
  2. Die festgelegte Version des Schlüssels. Jeder Schlüssel wird auf die Version festgelegt, die am Tag seiner Erstellung aktuell ist. Beim Rotieren eines Schlüssels bleibt die Version des vorherigen erhalten.
  3. Die Basisversion (2026-10-01) für Schlüssel, die vor Einführung der Versionierung erstellt wurden.

Cord erzeugt jede Antwort in ihrer neuesten Form und wandelt sie Änderung für Änderung in die ermittelte Version um. Jede Antwort enthält den Header Cord-Version mit der Version, in der geantwortet wurde.

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

Derzeit lässt sich die festgelegte Version eines bestehenden Schlüssels nicht ändern. Um auf eine neue Version zu wechseln, senden Sie den Header Cord-Version in Ihren Anfragen oder erstellen Sie einen neuen Schlüssel.

In den SDKs und der CLI

Die offiziellen Clients senden immer die Version, mit der sie gebaut wurden; ein Update von Cord ändert also nicht, was sie lesen:

Client Gesendete Version So ändern Sie sie
@flouviahq/node CORD_API_VERSION (2026-10-01) new Cord(sk, { apiVersion: '2026-10-01' })
@flouviahq/elements CORD_API_VERSION (2026-10-01) Wird mit dem Paket aktualisiert.
@flouviahq/cli 2026-10-01 Wird mit dem Paket aktualisiert. 
import { Cord, CORD_API_VERSION } from '@flouviahq/node';

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

Webhooks

Jeder Webhook-Endpoint wird auf die Version festgelegt, die am Tag seiner Erstellung aktuell ist – egal ob er in der Workbench, über POST /api/v1/webhooks oder mit einer Sitzung von cord listen erstellt wird. Das data jeder Zustellung wird in die Version dieses Endpoints umgewandelt, nicht in die des Schlüssels, der das Ereignis ausgelöst hat. Haben Sie zwei Endpoints mit unterschiedlichen Versionen, erhalten beide dasselbe Ereignis mit derselben id, jeweils in ihrer eigenen Form.

Zustellungen enthalten keinen Header Cord-Version, und es gibt keinen Header, um pro Zustellung eine andere Version anzufordern: Um eine andere Form zu erhalten, erstellen Sie einen neuen Endpoint.

Ungültige Version

Eine Version, die es nicht gibt, antwortet mit 400 und code: "invalid_api_version". Cord weicht nie stillschweigend auf eine andere Version aus. Die Meldung listet die verfügbaren Versionen auf:

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"
}

Auch das Format zählt: Cord-Version: 2026-10 oder latest führen zum selben Fehler.

Änderungsrichtlinie

Erfordert eine neue Version (erreicht Ihre Integration nie, ohne dass Sie sie anfordern):

  • ein Feld einer Antwort oder eines Webhooks entfernen oder umbenennen;
  • den Typ oder die Bedeutung eines Felds ändern;
  • einen Fehlercode ändern.

Kommt ohne neue Version, weil es eine sauber geschriebene Integration nicht bricht:

  • neue Felder in einer Antwort oder im data eines Webhooks;
  • neue Ereignistypen;
  • neue Endpoints und neue optionale Parameter.

Der Text des Felds error ist eine Meldung für Menschen und kann jederzeit verbessert werden: Programmieren Sie gegen code, nie gegen den Text.

Ihre Integration sollte Felder ignorieren, die sie nicht kennt, und einen unbekannten Ereignistyp als etwas behandeln, das sie verwerfen kann. Wenn Sie die Ereignisse eines Endpoints nicht ausgewählt haben, erhalten Sie alle, auch die, die Cord später hinzufügt.

Sobald es eine neue Version gibt, erscheint sie in der Tabelle oben mit den Änderungen.