# Introduction

The Bird API is a unified REST API for everything the platform does. This reference documents every public endpoint, generated from the same OpenAPI specification that drives the official SDKs, so the request and response shapes here are exactly what the wire carries.

The reference is grouped by resource into three sections:

- **Channels** — sending and message-level resources: email messages, broadcasts, suppressions, and per-channel configuration.
- **Products** — product surfaces built on the channels, such as templates and analytics.
- **Platform** — the resources that exist regardless of channel: workspaces, API keys, sending domains, dedicated IPs, IP pools, and webhooks.

Resource pages are deep-linked from the [guides](/docs): when a guide mentions an endpoint, the link lands on its reference entry here.

## Conventions

Every endpoint follows the same conventions. They are stated once here rather than repeated on each page.

- **Base path** — all endpoints live under `/v1` on a regional host such as `https://us1.platform.bird.com`. See [Base URLs & regions](/docs/api/regions).
- **Authentication** — requests carry an API key as a bearer token: `Authorization: Bearer bk_us1_...`. See [Authentication](/docs/api/authentication).
- **JSON, snake_case** — request and response bodies are JSON with `snake_case` field names (`created_at`, `workspace_id`), and requests must set `Content-Type: application/json`.
- **Timestamps** — all timestamps are RFC 3339 strings in UTC, in fields suffixed `_at` (`created_at`, `revoked_at`). Timestamp fields are server-assigned and read-only.
- **Typed resource IDs** — every ID carries a type prefix: `em_` for email messages, `dom_` for sending domains, `whk_` for webhook endpoints, `sup_` for suppressions, and so on. The prefix makes an ID self-describing in logs and prevents passing one resource's ID where another's is expected.
- **Partial updates use PATCH** — the API never uses `PUT`. A `PATCH` request changes only the fields you include; omitted fields are left untouched.
- **Errors** — every error response carries the same envelope, with a `type` for coarse branching, a stable `code`, a human-readable `message`, and the `request_id` to quote when contacting support. See [Errors](/docs/api/errors).
- **Pagination** — list endpoints use cursor-based pagination with a shared parameter set. See [Pagination](/docs/api/pagination).
- **Idempotency** — mutating endpoints accept an `Idempotency-Key` header so retries are safe. See [Idempotency](/docs/api/idempotency).

## Recommended clients

You can call the API with any HTTP client, but the official clients handle authentication, region selection, retries, and pagination for you:

- The official SDKs for [TypeScript](/docs/sdks/typescript), Go, and Python — typed methods over the curated public surface
- The [Bird CLI](/docs/cli) — the API from your terminal, also suited to scripts and agents

## Read next

- [Authentication](/docs/api/authentication) — how requests authenticate at the wire level
- [Base URLs & regions](/docs/api/regions) — regional hosts and the region model
- [Pagination](/docs/api/pagination) — cursors, page sizes, and sorting
- [Idempotency](/docs/api/idempotency) — safe retries for mutating requests
- [Errors](/docs/api/errors) — the error envelope and the full error catalog