A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Bird API is how an app or AI agent works with a Bird workspace: sending an SMS, WhatsApp, or email message over a channel, managing contacts and lists, running a conversation, or sending a one-time passcode to verify someone. Access is granted through an access key tied to a single workspace, and every call is scoped to that workspace. Bird can also push an event to a subscribed endpoint when a message arrives or changes status, so an integration learns about activity without polling.
How an app or AI agent connects to Bird determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the access key behind it, which is tied to one workspace.
The REST API is workspace-scoped and path-based, at https://api.bird.com, with no version segment in the path. A call authenticates with an access key sent in the Authorization header as 'AccessKey
Bird posts events to an endpoint registered through a webhook subscription. A subscription names the service, the event type, the endpoint URL, a signing key used to verify the request, and optional filters like channel id and message status. Event types follow a
An access key authenticates every API call. It is sent in the Authorization header as the word 'AccessKey' followed by a space and the key. An access key belongs to one workspace and represents that workspace's access. Bird's API reference does not document granular per-endpoint scopes on an access key, so a key cannot be narrowed to a single method through the API itself.
The Bird API is split into areas an agent can act on, like sending messages over channels, managing contacts and lists, running conversations, buying and looking up numbers, and sending one-time passcodes. A write in some areas sends real messages to real people or spends money on numbers.
Methods for creating channels and sending and reading messages over them.
Methods for managing contacts and the lists they belong to.
Methods for working with conversations and the messages inside them.
Methods for searching, buying, and looking up phone numbers.
Methods for sending and checking one-time passcodes.
Methods for requesting and retrieving organization-level reports.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Channels & messagingMethods for creating channels and sending and reading messages over them.8 | ||||||
| POST | /workspaces/{workspaceId}/channels/{channelId}/messages | Send a message over a channel, like an SMS, WhatsApp, or email, using a body or a template. | write | Channels write | Current | |
Requires an active channel. A request must set either body or template, not both. Multiple receivers are only allowed on the email channel. Acts onmessage Permission (capability) Channels writeVersionAvailable since the API’s base version Webhook event channel.outboundRate limit500 POST req/s per workspace (shared) SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/channels/{channelId}/messages | List messages for a channel. | read | Channels read | Current | |
Read-only. Acts onmessage Permission (capability) Channels readVersionAvailable since the API’s base version Webhook eventNone Rate limit50 GET req/s per workspace (shared) SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} | Retrieve a single message and its current status. | read | Channels read | Current | |
Read-only. Acts onmessage Permission (capability) Channels readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions | List interactions on a message, like reads, clicks, and reactions. | read | Channels read | Current | |
Read-only. Acts oninteraction Permission (capability) Channels readVersionAvailable since the API’s base version Webhook event channel.interactionRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/connectors | Create a connector from a template, which produces a channel to send and receive on. | write | Channels write | Current | |
A connector links the Bird platform to a third-party messaging provider and is the prerequisite for a channel. Acts onconnector Permission (capability) Channels writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/connectors | List the connectors set up in a workspace. | read | Channels read | Current | |
Read-only. Acts onconnector Permission (capability) Channels readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /workspaces/{workspaceId}/connectors/{connectorId} | Delete a connector and the channel associated with it. | write | Channels write | Current | |
Removing the connector removes its channel, so an integration can no longer send or receive on it. Acts onconnector Permission (capability) Channels writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/webhook-subscriptions | Subscribe an endpoint to channel events, like inbound, outbound, and interaction events. | write | Channels write | Current | |
The subscription names the service, event type, endpoint URL, a signing key, and optional filters like channel id and status. Acts onwebhook_subscription Permission (capability) Channels writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts & listsMethods for managing contacts and the lists they belong to.10 | ||||||
| POST | /workspaces/{workspaceId}/contacts | Create a contact, the central record for a customer's identifiers and attributes. | write | Contacts write | Current | |
A contact can carry multiple identifiers, like an email address and a phone number. Acts oncontact Permission (capability) Contacts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/contacts | List the contacts in a workspace. | read | Contacts read | Current | |
Read-only. Reaches every contact stored in the workspace. Acts oncontact Permission (capability) Contacts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/contacts/{contactId} | Retrieve a single contact. | read | Contacts read | Current | |
Read-only. Acts oncontact Permission (capability) Contacts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /workspaces/{workspaceId}/contacts/{contactId} | Update a contact's identifiers or attributes. | write | Contacts write | Current | |
A core write to a customer record. Acts oncontact Permission (capability) Contacts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /workspaces/{workspaceId}/contacts/{contactId} | Delete a contact from the workspace. | write | Contacts write | Current | |
Permanently removes the contact record. Acts oncontact Permission (capability) Contacts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/lists | Create a contact list. | write | Contacts write | Current | |
A list groups contacts for targeting and messaging. Acts onlist Permission (capability) Contacts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/lists | List the contact lists in a workspace. | read | Contacts read | Current | |
Read-only. Acts onlist Permission (capability) Contacts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/lists/{listId}/contacts | List the contacts in a given list. | read | Contacts read | Current | |
Read-only. Acts onlist Permission (capability) Contacts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/lists/{listId}/contacts | Add contacts to a list. | write | Contacts write | Current | |
Returns how many contacts were processed; a lower count than supplied means some were not added. Acts onlist Permission (capability) Contacts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/contacts/{contactId}/lists | Get the lists a contact is a member of. | read | Contacts read | Current | |
Read-only. Acts onlist Permission (capability) Contacts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConversationsMethods for working with conversations and the messages inside them.5 | ||||||
| POST | /workspaces/{workspaceId}/conversations | Create a conversation, optionally with an initial message. | write | Conversations write | Current | |
A conversation threads messages with a contact across channels. Acts onconversation Permission (capability) Conversations writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/conversations | List conversations across the workspace. | read | Conversations read | Current | |
Read-only. Returns at most 100 per page, default 10, paged with pageToken. Acts onconversation Permission (capability) Conversations readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/conversations/{conversationId} | Retrieve a single conversation. | read | Conversations read | Current | |
Read-only. Acts onconversation Permission (capability) Conversations readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/conversations/{conversationId}/messages | Send a message into a conversation. | write | Conversations write | Current | |
The sending participant type is one of accessKey, flow, or contact, with accessKey the common case. Acts onconversation_message Permission (capability) Conversations writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/conversations/{conversationId}/messages | List the messages in a conversation. | read | Conversations read | Current | |
Read-only. Acts onconversation_message Permission (capability) Conversations readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NumbersMethods for searching, buying, and looking up phone numbers.5 | ||||||
| GET | /workspaces/{workspaceId}/numbers-stock-items | Search the available phone numbers that can be bought. | read | Numbers read | Current | |
Read-only; lists numbers in stock, not numbers the workspace owns. Acts onnumber_stock_item Permission (capability) Numbers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/numbers-long-code | Buy a long-code phone number for the workspace. | write | Numbers write | Current | |
Buying a number spends real money on the workspace account. Acts onnumber Permission (capability) Numbers writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/numbers | List the phone numbers the workspace owns. | read | Numbers read | Current | |
Read-only. Acts onnumber Permission (capability) Numbers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/numbers-long-code/{longCodeNumberId} | Get the details of a long-code number the workspace owns. | read | Numbers read | Current | |
Read-only. Acts onnumber Permission (capability) Numbers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId}/network-lookup | Look up network details for a phone number. | read | Numbers read | Current | |
Read-only. A batch variant exists at /network-lookup/batch. Acts onnetwork_lookup Permission (capability) Numbers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Verify (OTP)Methods for sending and checking one-time passcodes.2 | ||||||
| POST | /workspaces/{workspaceId}/verify | Create a verification, sending a one-time passcode over SMS, WhatsApp, or email. | write | Verify write | Current | |
Requires an active channel. The code defaults to 6 digits and the length is configurable. Acts onverification Permission (capability) Verify writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces/{workspaceId}/verify/{verificationId} | Check a submitted code against a verification to confirm it is valid. | write | Verify write | Current | |
Confirms whether the code the person entered matches the one that was sent. Acts onverification Permission (capability) Verify writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReportingMethods for requesting and retrieving organization-level reports.3 | ||||||
| POST | /organizations/{organizationId}/reports | Request a report at the organization level. | write | Reporting write | Current | |
Reporting endpoints are scoped to the organization, not a single workspace. Acts onreport Permission (capability) Reporting writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{organizationId}/reports | List the reports for an organization. | read | Reporting read | Current | |
Read-only. Supports filtering by date range and pagination. Acts onreport Permission (capability) Reporting readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{organizationId}/reports/{reportId} | Retrieve a single report by id. | read | Reporting read | Current | |
Read-only. Acts onreport Permission (capability) Reporting readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Bird can notify an app when something happens on a channel, like an inbound message arriving, a sent message changing status, or a customer reading or clicking a message. It posts the event to a subscribed endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
| An inbound message arrived on a channel, for example sms.inbound. The message is created with a delivered status. | In-app only |
| A message sent by the app changed status, moving through accepted, processing, sent, delivered, or a failure like sending_failed or delivery_failed. | /workspaces/{workspaceId}/channels/{channelId}/messages |
| A customer interacted with a message, like reading it, clicking a link, or adding a reaction, for example email.interaction. | /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions |
Bird limits how fast an app can call, by a per-second request rate measured separately for reads and writes across a workspace, with individual channels also bounded by their downstream carrier.
Bird meters requests by a per-second rate across a workspace, measured separately for reads and writes. The default ceilings across all channels in a workspace are 50 GET requests per second and 500 POST requests per second. Going over returns HTTP 429 Too Many Requests, and Bird confirms the rejected request was not processed, so it can be retried safely. An individual channel can also be throttled by its downstream carrier below the workspace ceiling; when that happens Bird accepts and buffers the extra traffic and retries a buffered message up to 10 times with an exponential delay. Higher limits are arranged through support.
List endpoints page with a limit and a pageToken. For example, listing conversations returns at most 100 per page, with a default of 10, and pageToken fetches the next page.
A verification code defaults to 6 digits and the length is configurable. Sending to multiple recipients in one request is only supported on the email channel; other channels reject a request with more than one receiver.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | error.detailed | The request was malformed or invalid. The body carries a code, a message, and a details object. | Read the code and message, fix the request, and resend. The request is not retryable as-is. |
| 401 | unauthenticated | The access key was missing or invalid. | Send a valid access key in the Authorization header as 'AccessKey |
| 403 | forbidden | The access key is valid but not allowed to perform this request. | Confirm the key belongs to the right workspace and has access to the resource. |
| 404 | error.detailed | The requested resource does not exist or is not visible to this key. The body carries a code, a message, and a details object. | Verify the workspace, channel, or resource id in the path. |
| 422 | error.validation | The request failed validation. The body carries a code, a message, and a details object mapping each invalid field path to a list of problems. | Use the details map to fix the named fields, then resend. |
| 429 | too_many_requests | The workspace rate limit was exceeded. Bird confirms the request was not processed. | Back off and retry; the rejected request can be sent again safely. |
Bird does not put a version number in its API paths. There is a single, continuously updated API, and dated changes ship through the changelog.
Bird does not put a version number in its API paths; there is a single, continuously updated API rather than dated versions to pin. Dated changes ship through the changelog. The current Bird API supersedes the legacy MessageBird REST API, which lived on a separate host.
User management was redesigned with improved role assignments and workspace access controls in Organization Settings.
Contacts and CRM access permissions changed and are no longer included by default for the Developer role, so a person needs a specific role to reach that data.
Visibility of the developer app was restricted to users with a developer or workspace admin role.
There is no version to pin; track the changelog for changes.
Bird changelog ↗Bollard AI sits between a team's AI agents and Bird. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.