URL de base et régions

L'Bird API est servie depuis des hôtes régionaux. Chaque requête est dirigée directement vers la région qui héberge les données de votre organisation. L'API ne fournit pas d'URL de plan de données globale.

Les codes de région sont composés de deux lettres minuscules pour la géographie plus un chiffre d'instance (^[a-z]{2}[0-9]+$). us1 et eu1 sont actifs ; le schéma prend en charge de futures régions telles que us2 et ap1 sans modification côté client.

Chaque organisation se voit attribuer une région à l'inscription. La région est détectée à partir de votre localisation, peut être modifiée avant confirmation, et est immuable en v1. L'espace de travail, les clés API, les messages, les données des destinataires et les journaux d'événements restent dans cette région. Ils ne sont jamais répliqués entre les régions. Cette séparation prend en charge les engagements de résidence des données, comme le stockage et le traitement dans l'UE pour une organisation de l'UE.

Seules l'authentification et l'administration des comptes (/v1/auth, /v1/admin) opèrent sur des données répliquées globalement, ce qui explique pourquoi elles sont servies depuis l'hôte non régional platform.bird.com.

Une clé API encode sa région dans son préfixe : les clés bk_us1_... appartiennent à us1, les clés bk_eu1_... à eu1. Envoyez chaque clé à son hôte régional correspondant.

Une requête qui atteint la mauvaise région est rejetée avec 421 Misdirected Request au lieu d'être transférée. Le message d'erreur indique l'hôte correct :

{
  "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": "..."
}

Chaque réponse API contient également un en-tête X-Bird-Region indiquant la région qui l'a servie, utile pour confirmer dans quelle région une requête a effectivement atterri.

Les SDK officiels et le CLI extraient la région du préfixe de la clé et choisissent l'hôte. Avec une clé bk_eu1_..., chaque appel est dirigé vers eu1.platform.bird.com sans configuration. Vous pouvez remplacer l'hôte déduit pour un environnement de test : utilisez baseUrl dans le SDK TypeScript, option.WithBaseURL dans le SDK Go, ou --base-url (ou BIRD_API_URL) sur le CLI.