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, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace, and the developer tools (Webhooks and Documentation, the docs search API). Sending domains, inbound email, and contacts and audiences have reference pages without a sidebar entry. Start from Create a sending domain, Create an inbound address, Create a contact, and Create an audience, or from their guides: Sending domains, Receiving email, Contacts, and Audiences. The Voice section includes calls, leg logs, trunks, numbers, caller IDs, destinations, and SIP session credentials. Voice statistics remain available through the dashboard and CLI. 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: when a guide mentions an endpoint, the link lands on its reference entry here.

For coding agents

Point an agent at these machine-readable sources:

• OpenAPI specification: every public endpoint, schema, and error code, also served as YAML. The SDKs are generated from the same file.
• API index: the API guides, every operation reference, and the public errors, grouped by product and linked to their Markdown pages.
• Docs index: every published English docs page, grouped by section and product.
• Site index: products, quickstarts, and agent tooling across bird.com.
• MCP server: hosted tools at mcp.bird.com that act on your workspace after a browser sign-in.
• Bird CLI: the API from a terminal. CLI for agents covers its JSON output and exit codes.
• Markdown pages: append .md to any docs URL, as in https://bird.com/docs/api.md, or send Accept: text/markdown.

Product map

Each table lists the calls an integration makes, in order, with a link to each call's reference page and to the product's guides.

Email

SMS

Verify

Other products

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.
• Authentication: requests carry an API key as a bearer token: Authorization: Bearer bk_us1_.... See 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: a PATCH request changes only the fields you include, and leaves omitted fields untouched. A few subresources that you address by name in the URL are written with PUT, which replaces that subresource in full.
• 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.
• Pagination: list endpoints use cursor-based pagination with a shared parameter set. See Pagination.
• Idempotency: mutating endpoints accept an Idempotency-Key header so retries are safe. See Idempotency-Key header.
• Deprecations: a renamed field keeps working under its old name, and a response says so with a Deprecation header. See 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, Go, and Python: typed methods over the curated public surface
• The Bird CLI: the API from your terminal, also suited to scripts and agents

Run it in Postman

The whole API is also a Postman collection, converted from this same specification, with an example request and response on every endpoint. Import the environment for your region, set apiKey to a workspace API key, and send any request.

You can also download the collection and an environment for us1 or eu1 directly.

Read next

• Authentication: how requests authenticate at the wire level
• Base URLs and regions: regional hosts and the region model
• Pagination: cursors, page sizes, and sorting
• Idempotency-Key header: safe retries for mutating requests
• Error responses: the error envelope and the full error catalog
• Deprecations: what a superseded field name still does, and how to migrate off one