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

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.
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 — 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.

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 not forwarded — it is rejected with 421 Misdirected Request, and 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 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.

Related