Basis-URL's en regio's

De Bird API wordt bediend vanuit regionale hosts. Elk verzoek gaat rechtstreeks naar de regio waar de data van je organisatie staan. De API biedt geen globale data-plane-URL.

Regiocodes bestaan uit twee kleine letters voor de geografie plus een instantiecijfer (^[a-z]{2}[0-9]+$). us1 en eu1 zijn nu actief; het schema ondersteunt toekomstige regio's zoals us2 en ap1 zonder clientwijzigingen.

Elke organisatie krijgt bij aanmelding een regio toegewezen. De regio wordt afgeleid van je locatie, kan worden gewijzigd voordat je bevestigt en is onveranderlijk in v1. De werkruimte, API-sleutels, berichten, ontvangerdata en eventlogs blijven in die regio. Ze worden nooit gerepliceerd naar andere regio's. Deze scheiding ondersteunt dataresidentie-afspraken, zoals EU-opslag en -verwerking voor een EU-organisatie.

Alleen authenticatie en accountbeheer (/v1/auth, /v1/admin) werken op globaal gerepliceerde data, en daarom worden ze bediend vanuit de niet-regionale host platform.bird.com.

Een API-sleutel codeert de regio in zijn prefix: bk_us1_...-sleutels horen bij us1, bk_eu1_...-sleutels bij eu1. Stuur elke sleutel naar de bijbehorende regionale host.

Een verzoek dat de verkeerde regio bereikt, wordt afgewezen met 421 Misdirected Request in plaats van doorgestuurd. Het foutbericht vermeldt de juiste 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": "..."
}

Elk API-antwoord bevat ook een X-Bird-Region-header met de regio die het verzoek heeft afgehandeld, handig om te bevestigen in welke regio een verzoek daadwerkelijk is terechtgekomen.

De officiële SDK's en de CLI lezen de regio uit het sleutelprefix en kiezen de host. Met een bk_eu1_...-sleutel gaat elke aanroep zonder configuratie naar eu1.platform.bird.com. Je kunt de afgeleide host overschrijven voor een testomgeving: gebruik baseUrl in de TypeScript-SDK, option.WithBaseURL in de Go-SDK, of --base-url (of BIRD_API_URL) op de CLI.