Documentation
Sign inGet started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Base URLs and regions

The Bird API is served from regional hosts. Each request goes directly to the region that holds your organization's data. The API does not provide a global data-plane URL.
Base URLServes
https://us1.platform.bird.comAll /v1 data-plane endpoints for organizations in us1
https://eu1.platform.bird.comAll /v1 data-plane endpoints for organizations in eu1
https://platform.bird.comRegion-independent surfaces only: /v1/auth and /v1/admin
Region codes are two lowercase letters for the geography plus an instance digit (^[a-z]{2}[0-9]+$). us1 and eu1 are live today; the scheme accommodates future regions such as us2 and ap1 without any client change.

Organizations are pinned to a region

Every organization is assigned a region at signup. The region is detected from your location, can be changed before you confirm, and is immutable in v1. All of the organization's workspaces, API keys, messages, recipient data, and event logs remain in that region. They are never replicated across regions. This separation supports data-residency commitments such as EU storage and processing for an EU organization.
Only authentication and account administration (/v1/auth, /v1/admin) operate on globally replicated data, which is why they are served from the non-region host platform.bird.com.

Routing: the key selects the host

An API key encodes its region in its prefix: bk_us1_... keys belong to us1, bk_eu1_... keys to eu1. Send each key to its matching regional host.
A request that reaches the wrong region is rejected with 421 Misdirected Request instead of being forwarded. The error message names the correct host:
Code example
{
  "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": "..."
}
Every API response also carries an X-Bird-Region header naming the region that served it, useful when confirming which region a request actually landed in.

SDKs and the CLI route automatically

The official SDKs and the CLI parse the region from the key prefix and pick the host. With a bk_eu1_... key, every call goes to eu1.platform.bird.com without configuration. You can override the inferred host for a test environment: use baseUrl in the TypeScript SDK, option.WithBaseURL in the Go SDK, or --base-url (or BIRD_API_URL) on the CLI.

Related