URL di base e regioni

Il Bird API è servito da host regionali. Ogni richiesta va direttamente alla regione che contiene i dati della tua organizzazione. Il API non fornisce un URL data-plane globale.

I codici di regione sono due lettere minuscole per la geografia più una cifra di istanza (^[a-z]{2}[0-9]+$). us1 e eu1 sono attivi; lo schema supporta regioni future come us2 e ap1 senza alcuna modifica al client.

A ogni organizzazione viene assegnata una regione al momento della registrazione. La regione viene rilevata dalla tua posizione, può essere modificata prima della conferma ed è immutabile nella v1. Lo spazio di lavoro, le chiavi API, i messaggi, i dati dei destinatari e i log degli eventi restano in quella regione. Non vengono mai replicati tra regioni diverse. Questa separazione supporta impegni di residenza dei dati come l'archiviazione e l'elaborazione in UE per un'organizzazione UE.

Solo l'autenticazione e l'amministrazione dell'account (/v1/auth, /v1/admin) operano su dati replicati globalmente, motivo per cui sono serviti dall'host non regionale platform.bird.com.

Una chiave API codifica la propria regione nel prefisso: le chiavi bk_us1_... appartengono a us1, le chiavi bk_eu1_... a eu1. Invia ogni chiave all'host regionale corrispondente.

Una richiesta che raggiunge la regione sbagliata viene rifiutata con 421 Misdirected Request anziché essere inoltrata. Il messaggio di errore indica l'host corretto:

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

Ogni risposta API include anche un header X-Bird-Region che indica la regione che l'ha servita, utile per verificare in quale regione è effettivamente arrivata una richiesta.

Gli SDK ufficiali e il CLI leggono la regione dal prefisso della chiave e selezionano l'host. Con una chiave bk_eu1_..., ogni chiamata va a eu1.platform.bird.com senza configurazione. Puoi sovrascrivere l'host dedotto per un ambiente di test: usa baseUrl nell'SDK TypeScript SDK, option.WithBaseURL nell'SDK Go SDK, oppure --base-url (o BIRD_API_URL) sul CLI.