Basis-URLs und Regionen

Die Bird API wird über regionale Hosts bereitgestellt. Jede Anfrage geht direkt an die Region, die die Daten Ihrer Organisation enthält. Die API stellt keine globale Data-Plane-URL bereit.

Regionscodes bestehen aus zwei Kleinbuchstaben für die Geografie plus einer Instanzziffer (^[a-z]{2}[0-9]+$). us1 und eu1 sind bereits aktiv; das Schema unterstützt zukünftige Regionen wie us2 und ap1 ohne Client-Änderung.

Jeder Organisation wird bei der Registrierung eine Region zugewiesen. Die Region wird anhand Ihres Standorts erkannt, kann vor der Bestätigung geändert werden und ist in v1 unveränderlich. Der Workspace, API-Schlüssel, Nachrichten, Empfängerdaten und Event-Logs verbleiben in dieser Region. Sie werden nie regionsübergreifend repliziert. Diese Trennung unterstützt Anforderungen an die Datenresidenz, etwa EU-Speicherung und -Verarbeitung für eine EU-Organisation.

Nur Authentifizierung und Kontoverwaltung (/v1/auth, /v1/admin) arbeiten mit global replizierten Daten, weshalb sie über den regionsunabhängigen Host platform.bird.com bereitgestellt werden.

Ein API-Schlüssel kodiert seine Region im Präfix: bk_us1_...-Schlüssel gehören zu us1, bk_eu1_...-Schlüssel zu eu1. Senden Sie jeden Schlüssel an den passenden regionalen Host.

Eine Anfrage, die die falsche Region erreicht, wird mit 421 Misdirected Request abgelehnt, statt weitergeleitet zu werden. Die Fehlermeldung nennt den richtigen Host:

{
  "type": "misdirected_error",
  "code": "E01010",
  "name": "MisdirectedRequest",
  "message": "Organization belongs to region eu1 but this request reached us1. Send the request to eu1.platform.bird.com.",
  "request_id": "..."
}

Jede API-Antwort enthält außerdem einen X-Bird-Region-Header mit dem Namen der Region, die sie bedient hat – nützlich, um zu prüfen, in welcher Region eine Anfrage tatsächlich gelandet ist.

Die offiziellen SDKs und die CLI lesen die Region aus dem Schlüsselpräfix und wählen den Host. Mit einem bk_eu1_...-Schlüssel geht jeder Aufruf ohne Konfiguration an eu1.platform.bird.com. Sie können den abgeleiteten Host für eine Testumgebung überschreiben: Verwenden Sie baseUrl im TypeScript-SDK, option.WithBaseURL im Go-SDK oder --base-url (bzw. BIRD_API_URL) in der CLI.