URLs base y regiones

La Bird API se sirve desde hosts regionales. Cada solicitud va directamente a la región que almacena los datos de tu organización. La API no proporciona una URL global de plano de datos.

Los códigos de región son dos letras minúsculas para la geografía más un dígito de instancia (^[a-z]{2}[0-9]+$). us1 y eu1 están activos; el esquema admite regiones futuras como us2 y ap1 sin ningún cambio en el cliente.

A cada organización se le asigna una región en el registro. La región se detecta a partir de tu ubicación, se puede cambiar antes de confirmar y es inmutable en v1. El espacio de trabajo, las claves API, los mensajes, los datos de destinatarios y los registros de eventos permanecen en esa región. Nunca se replican entre regiones. Esta separación respalda compromisos de residencia de datos, como el almacenamiento y procesamiento en la UE para una organización de la UE.

Solo la autenticación y la administración de cuentas (/v1/auth, /v1/admin) operan sobre datos replicados globalmente, por eso se sirven desde el host sin región platform.bird.com.

Una clave API codifica su región en el prefijo: las claves bk_us1_... pertenecen a us1, las claves bk_eu1_... a eu1. Envía cada clave a su host regional correspondiente.

Una solicitud que llega a la región incorrecta se rechaza con 421 Misdirected Request en lugar de reenviarse. El mensaje de error indica el host correcto:

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

Cada respuesta API también incluye un encabezado X-Bird-Region que indica la región que la sirvió, útil para confirmar a qué región llegó realmente una solicitud.

Los SDKs oficiales y la CLI extraen la región del prefijo de la clave y seleccionan el host. Con una clave bk_eu1_..., cada llamada va a eu1.platform.bird.com sin configuración. Puedes sobrescribir el host inferido para un entorno de pruebas: usa baseUrl en el SDK de TypeScript, option.WithBaseURL en el SDK de Go, o --base-url (o BIRD_API_URL) en la CLI.