A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Twilio API is how an app or AI agent works with Twilio's communication channels: sending an SMS, MMS, or WhatsApp message, placing and controlling a phone call, buying or releasing a phone number, and managing the account and its subaccounts. Access is granted through HTTP Basic auth, with either the Account SID and Auth Token or an API key, and the core REST API has no per-action OAuth scopes, so the credential itself sets the whole boundary. A state change like a delivered message or an answered call is reported back through a status-callback webhook.
How an app or AI agent connects to Twilio determines what it can reach. There is the REST API for making calls, status-callback webhooks for receiving updates, and a hosted documentation server for agents, and each is governed by the credential behind it. The core REST API authenticates with a single account-wide credential that carries no per-action scopes, so the credential itself sets the whole boundary.
The core REST API answers at https://api.twilio.com, and every path carries the dated version 2010-04-01. Most resources live under /2010-04-01/Accounts/{AccountSid}/. It takes form-encoded request bodies and returns JSON when the path ends in .json (XML and CSV are also available on the 2010 API). Newer products use their own base, like messaging.twilio.com/v1, which returns JSON only. A request authenticates with HTTP Basic auth, and the core API has no per-action OAuth scopes, so the credential sets the whole boundary.
Twilio POSTs to a URL set on a message or call to report status changes, like a message being delivered or a call being answered. A message callback carries MessageStatus and, on failure, an ErrorCode; a call callback carries CallStatus, and StatusCallbackEvent selects which call events are sent. Inbound messages and calls are also delivered to the webhook URL configured on the receiving phone number.
Twilio hosts a documentation MCP server at https://mcp.twilio.com/docs, in public beta, that an agent points its client at with no installation and no authentication. It indexes the public API specs across 1,800+ endpoints and 30+ products and exposes twilio__search and twilio__retrieve tools in a search-then-retrieve flow. It is read-only: it returns API documentation and does not execute API calls. A separate self-hostable server, the @twilio-alpha/mcp npm package from twilio-labs, turns Twilio's OpenAPI spec into executable MCP tools and authenticates with an API key SID and secret.
An API key has its own SID (SK...) and a secret, and is sent through HTTP Basic auth with the key SID as the username and the secret as the password. Twilio recommends using API keys for production, because a key can be revoked on its own without rotating the Auth Token. A Standard key authenticates REST API requests; the secret is shown only once, when the key is created. An API key carries no per-action scopes on the core REST API.
The Account SID (AC...) is the username and the Auth Token is the password in HTTP Basic auth. This is the account's master credential and can call the entire API, so Twilio recommends limiting it to local testing and using API keys in production. If the Account SID and Auth Token leak, the whole account is compromised.
The Twilio API is split into areas an agent can act on, like sending messages, placing and controlling calls, buying and releasing phone numbers, and managing the account and its subaccounts. The core REST API has no granular per-action permissions, so the credential used can reach every area at once unless something in front of it narrows the access.
Send an SMS, MMS, or WhatsApp message, read and update sent messages, and manage Messaging Services that pool numbers for sending.
Place an outbound call, fetch and list calls, redirect or end a call in progress, and read or delete call recordings.
Search for numbers available to buy, provision a number onto the account, update its settings, and release a number.
Read account details, create and list subaccounts, and update an account's status to suspend, reactivate, or close it.
Create, read, update, and delete the API keys that authenticate REST API requests.
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 | |
|---|---|---|---|---|---|---|
MessagingSend an SMS, MMS, or WhatsApp message, read and update sent messages, and manage Messaging Services that pool numbers for sending.8 | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/Messages.json | Send an outbound SMS, MMS, or WhatsApp message. | write | — | Current | |
The core REST API has no per-action scopes; any valid Account SID and Auth Token, or API key, can call this. A StatusCallback URL can be set to receive delivery updates. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event message-statusRate limitThroughput is the account's messages-per-second for the sending number; excess queues. SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json | Fetch a single message by its SID. | read | — | Current | |
Read-only. No per-action scope on the core REST API. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Messages.json | List messages sent from or received by the account, with optional date and number filters. | read | — | Current | |
Read-only. Paginated with PageSize and next_page_uri. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json | Update a message's body, used to redact the content of a sent or in-progress message. | write | — | Current | |
Posting an empty body redacts the message. No per-action scope on the core REST API. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json | Delete a message record from the account. | write | — | Current | |
Removes the message record. No per-action scope on the core REST API. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/Services | Create a Messaging Service, a pool of numbers and settings used to send messages at scale. | write | — | Current | |
On the product API base messaging.twilio.com/v1, not the 2010-04-01 base. No per-action scope. Acts onmessaging_service Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/Services | List the account's Messaging Services. | read | — | Current | |
Read-only. On messaging.twilio.com/v1. Acts onmessaging_service Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/Services/{Sid} | Delete a Messaging Service, returning its phone numbers and short codes to the account. | write | — | Current | |
Deleting a Service used for US A2P 10DLC immediately halts that messaging. On messaging.twilio.com/v1. Acts onmessaging_service Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VoicePlace an outbound call, fetch and list calls, redirect or end a call in progress, and read or delete call recordings.7 | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/Calls.json | Place an outbound call to a phone number, SIP address, or client identifier. | write | — | Current | |
A StatusCallback URL and StatusCallbackEvent set which call events are sent back. No per-action scope. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call-statusRate limitSubject to the account's REST API concurrency limit. SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json | Fetch a single call by its SID. | read | — | Current | |
Read-only. No per-action scope on the core REST API. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Calls.json | List calls made to and from the account, with optional filters. | read | — | Current | |
Read-only. Paginated with PageSize and next_page_uri. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json | Modify a call in progress, redirecting it to new TwiML or ending it. | write | — | Current | |
Setting Status to completed ends a live call. No per-action scope. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json | Fetch the metadata of a single call recording. | read | — | Current | |
Read-only. Metadata is returned in JSON or XML. Acts onrecording Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Recordings.json | List the account's call recordings, with optional filters. | read | — | Current | |
Read-only. Paginated. Acts onrecording Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json | Delete a recording from the account. | write | — | Current | |
Sets the recording status to deleted; metadata is retained for 40 days. No per-action scope. Acts onrecording Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Phone numbersSearch for numbers available to buy, provision a number onto the account, update its settings, and release a number.6 | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json | Search for local phone numbers available to buy, filtered by area code, capabilities, or pattern. | read | — | Current | |
Read-only search; buying happens through IncomingPhoneNumbers. No per-action scope. Acts onavailable_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json | Provision a phone number onto the account by buying it. | write | — | Current | |
Buys a real number and starts billing for it. No per-action scope. Acts onincoming_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json | Fetch a single phone number owned by the account. | read | — | Current | |
Read-only. No per-action scope on the core REST API. Acts onincoming_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json | List the phone numbers owned by the account. | read | — | Current | |
Read-only. Paginated. Acts onincoming_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json | Update a phone number's settings, like the webhook URLs for incoming calls and messages. | write | — | Current | |
Changes how the number routes inbound traffic. No per-action scope. Acts onincoming_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json | Release a phone number from the account. | write | — | Current | |
Releasing a number gives it up, and it may not be recoverable. No per-action scope. Acts onincoming_phone_number Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account & subaccountsRead account details, create and list subaccounts, and update an account's status to suspend, reactivate, or close it.4 | ||||||
| POST | /2010-04-01/Accounts.json | Create a subaccount under the main account. | write | — | Current | |
Subaccounts isolate resources and billing. No per-action scope. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{Sid}.json | Fetch an account or subaccount by its SID. | read | — | Current | |
Read-only. No per-action scope on the core REST API. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts.json | List the accounts and subaccounts the credential can reach. | read | — | Current | |
Read-only. Paginated. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2010-04-01/Accounts/{Sid}.json | Update an account, including its Status to suspend, reactivate, or close it. | write | — | Current | |
Setting Status to closed permanently closes a subaccount. No per-action scope. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
API keysCreate, read, update, and delete the API keys that authenticate REST API requests.4 | ||||||
| POST | /2010-04-01/Accounts/{AccountSid}/Keys.json | Create a Standard API key used to authenticate REST API requests. | write | — | Current | |
The secret is returned once, at creation. A key can call the whole API. No per-action scope. Acts onkey Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Keys/{Sid}.json | Fetch a single API key's details. | read | — | Current | |
Read-only; the secret is never returned again. No per-action scope. Acts onkey Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2010-04-01/Accounts/{AccountSid}/Keys.json | List the account's API keys. | read | — | Current | |
Read-only. Paginated. Acts onkey Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /2010-04-01/Accounts/{AccountSid}/Keys/{Sid}.json | Delete an API key, revoking its access to the REST API. | write | — | Current | |
Immediately stops any request using that key. No per-action scope. Acts onkey Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Twilio can notify an app when something happens, like a message reaching its recipient or a call being answered. It sends an HTTP request, called a status callback, to a URL set on the message or call, so an integration learns the outcome without polling.
| Event | What it signals | Triggered by |
|---|---|---|
MessageStatus callback | Twilio POSTs to the StatusCallback URL as a message moves through its lifecycle, with MessageStatus values like queued, sending, sent, delivered, undelivered, and failed. When the status is undelivered or failed, an ErrorCode says why. | /2010-04-01/Accounts/{AccountSid}/Messages.json |
CallStatus callback | Twilio POSTs to the StatusCallback URL on a call's status events, with CallStatus values like queued, ringing, in-progress, completed, busy, no-answer, canceled, and failed. StatusCallbackEvent selects which of initiated, ringing, answered, and completed are sent. | /2010-04-01/Accounts/{AccountSid}/Calls.json |
Twilio limits how fast an app can call the REST API through a per-account concurrency ceiling, and limits message sending separately through a per-second throughput that depends on the phone number type.
Twilio limits the REST API by a per-account concurrency ceiling on how many requests run at once, not by a per-method point cost; exceeding it returns HTTP 429 with error 20429. Message sending is limited separately by throughput, measured in message segments per second (MPS) and tied to the sending number type: a US or Canada long code defaults to 1 MPS, a toll-free number defaults to higher rates, and a short code can reach about 100 MPS. Requests above the sending number's MPS queue rather than fail, with account and campaign queues holding up to about 10 hours of segments. Inbound messages are queued at up to 500 per second per destination number.
List endpoints are page-based. PageSize sets how many resources a page returns (default 50), page is the zero-indexed page number, and the response carries next_page_uri, previous_page_uri, and first_page_uri to walk the list. Following next_page_uri is preferred over building page URLs by hand, and the official SDKs auto-paginate.
A list page returns up to the PageSize requested, defaulting to 50. The 2010-04-01 API can return JSON, XML, or CSV by file extension on the path; product APIs return JSON only. A deleted recording's metadata is retained for 40 days.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 21211 | The 'To' phone number is not a valid number. The request was well-formed but a parameter is invalid. | Validate and format the destination number in E.164 (like +14155551234) before sending, and do not retry as-is. |
| 400 | 21608 | The 'To' number is not verified for this account. On a trial account, messages can only go to verified numbers. | Verify the destination number in the Console, or upgrade the account past the trial limit. |
| 400 | 21610 | The message can't be sent because the recipient has unsubscribed (replied STOP) from this number. | Stop sending to that recipient on that number, or send from a number they have not opted out of. |
| 401 | 20003 | Permission denied: authentication failed, usually a wrong or revoked Account SID, Auth Token, or API key. | Check the credential being sent, and rotate it if it is compromised. |
| 404 | 20404 | The requested resource was not found, because the SID is wrong or the resource is not visible to this credential. | Confirm the resource SID and that the credential's account owns it. |
| 429 | 20429 | Too many requests: the account's REST API concurrency limit was exceeded. | Back off and retry with exponential backoff, and smooth the request rate. |
| 500 | 20500 | An internal Twilio server error. It is rare and not caused by the request. | Retry with backoff, and contact Twilio support if it persists. |
Twilio pins its core REST API to a single dated version, 2010-04-01, which appears in every request path. New features ship inside that version rather than as new dated versions, and individual products ship their own dated changes through the changelog.
The core REST API at api.twilio.com is pinned to the dated version 2010-04-01, which appears in every request path. Twilio has kept it as the stable version, shipping new features inside it rather than minting new dated versions for the core API. Individual products use their own versioned bases (like messaging.twilio.com/v1) and ship dated changes through the product changelog.
Typing indicators became available across RCS, WhatsApp, and Apple Messages for Business through a unified V3 API with consistent JSON payloads.
The Conference list endpoint's behavior is changing on 13 July 2026 to default to returning only in-progress conferences rather than conferences of every status.
SMS data residency for the EU reached general availability in the Ireland (IE1) region, with full Messaging Service support.
The deadline for cipher suite security updates on REST API endpoints was extended to 18 November 2026 to give customers time to migrate.
The 2010-04-01 path version is stable; track the changelog for product-level changes.
Twilio product changelog ↗Bollard AI sits between a team's AI agents and Twilio. Twilio's core API has no built-in per-action permissions, so one key can send messages, place calls, and buy numbers alike. Bollard adds that boundary, granting each agent only the areas it needs, and every call is checked and logged.