URLs base e regiões

A Bird API é servida a partir de hosts regionais. Cada requisição vai diretamente para a região que contém os dados da sua organização. A API não fornece uma URL global de data plane.

Os códigos de região são duas letras minúsculas para a geografia mais um dígito de instância (^[a-z]{2}[0-9]+$). us1 e eu1 estão ativos; o esquema acomoda regiões futuras como us2 e ap1 sem nenhuma alteração no cliente.

Toda organização recebe uma região no momento do cadastro. A região é detectada a partir da sua localização, pode ser alterada antes da confirmação e é imutável na v1. O espaço de trabalho, as chaves API, as mensagens, os dados de destinatários e os logs de eventos permanecem nessa região. Eles nunca são replicados entre regiões. Essa separação sustenta compromissos de residência de dados, como armazenamento e processamento na UE para uma organização da UE.

Apenas autenticação e administração de conta (/v1/auth, /v1/admin) operam sobre dados replicados globalmente, e por isso são servidos a partir do host sem região platform.bird.com.

Uma chave API codifica sua região no prefixo: chaves bk_us1_... pertencem a us1, chaves bk_eu1_... a eu1. Envie cada chave para o host regional correspondente.

Uma requisição que chega à região errada é rejeitada com 421 Misdirected Request em vez de ser encaminhada. A mensagem de erro indica o host correto:

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

Toda resposta API também inclui um header X-Bird-Region com o nome da região que a atendeu, útil para confirmar em qual região a requisição realmente chegou.

Os SDKs oficiais e a CLI extraem a região do prefixo da chave e escolhem o host. Com uma chave bk_eu1_..., todas as chamadas vão para eu1.platform.bird.com sem configuração. Você pode sobrescrever o host inferido para um ambiente de teste: use baseUrl no SDK do TypeScript, option.WithBaseURL no SDK do Go, ou --base-url (ou BIRD_API_URL) na CLI.