# 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 sidebar groups the most-used resources: **Sending Email**, **Email Stats**, **Suppressions**, **Verify**, **Webhooks**, and **Documentation** (the docs search API). Other public endpoints, including sending domains, inbound email, contacts and audiences, SMS, and WhatsApp, are reachable through search and the deep links in their guides. Workspaces, API keys, and dedicated IPs are managed in the dashboard rather than the public API.

Resource pages are deep-linked from the [guides](/docs/guides): 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`, `delivered_at`). Resource timestamps like `created_at` are server-assigned and read-only; a few request fields, such as `scheduled_at`, are timestamps you supply.
- **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