Base URLs & regions

The Bird API is served from regional hosts. There is no single global data-plane URL — each request goes directly to the region that holds your organization's data.

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.

Every organization is assigned a region at signup — auto-detected from your location, overridable before you confirm — and the assignment is immutable in v1. All of the organization's workspaces, API keys, messages, recipient data, and event logs live in that one region and are never replicated across regions, which is what makes data-residency commitments (such as GDPR-driven EU residency) provable: an EU organization's data is stored and processed in the EU, full stop. See the data residency article for the compliance details.

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.

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 not forwarded — it is rejected with 421 Misdirected Request, and the error message names the correct 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": "..."
}

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.

The official SDKs and the CLI parse the region out of the key prefix and pick the host for you — with a bk_eu1_... key, every call goes to eu1.platform.bird.com without configuration. You can override the inferred host when needed (for example, against a test environment): baseUrl in the TypeScript SDK, option.WithBaseURL in the Go SDK, and --region on the CLI.