# 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 by product: **Email**, **SMS**, **Voice**, **Realtime**, **Verify**, and the developer tools (**Webhooks** and **Documentation**, the docs search API). Other public endpoints, including sending domains, inbound email, contacts and audiences, and WhatsApp, are reachable through search and the deep links in their guides. Voice is on the API one resource at a time, starting with the call log; its trunk, caller ID, destination and statistics reads are on the dashboard and the CLI meanwhile. Workspace settings, 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 and 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.
- **Query parameters are strict**: a request carrying a query parameter the endpoint does not document is rejected with `422` (`E01029`) rather than ignored. Check spelling against the endpoint's parameter list.
- **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 [Error responses](/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-Key header](/docs/api/idempotency).
- **Deprecations**: a renamed field keeps working under its old name, and a response says so with a `Deprecation` header. See [Deprecations](/docs/api/deprecations).

## 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 and regions](/docs/api/regions): regional hosts and the region model
- [Pagination](/docs/api/pagination): cursors, page sizes, and sorting
- [Idempotency-Key header](/docs/api/idempotency): safe retries for mutating requests
- [Error responses](/docs/api/errors): the error envelope and the full error catalog
- [Deprecations](/docs/api/deprecations): what a superseded field name still does, and how to migrate off one