# 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 URL                        | Serves                                                       |
| ------------------------------- | ------------------------------------------------------------ |
| `https://us1.platform.bird.com` | All `/v1` data-plane endpoints for organizations in `us1`    |
| `https://eu1.platform.bird.com` | All `/v1` data-plane endpoints for organizations in `eu1`    |
| `https://platform.bird.com`     | Region-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.

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](/docs/api/authentication) 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:

```json
{
  "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

- [Authentication](/docs/api/authentication) — key format and failure responses
- [Supported countries & restrictions](/docs/knowledge-base/policies/supported-countries) — delivery coverage and the residency choice at signup