Twilio publishes its OpenAPI specs at twilio/twilio-oai, the same descriptions Twilio uses to validate its own API and generate its official SDKs. There's no single combined spec file — Twilio ships one OpenAPI document per product, roughly 60 files covering everything from core Messaging to Flex to Conversations. Twilio already ships official, actively maintained SDKs for Node, Python, Java, C#, PHP, and Ruby, so generating your own client makes sense mainly for other languages, narrower internal wrappers around specific products, or agent tooling.
Where the spec lives
| Fact | Value |
|---|---|
| Repo | twilio/twilio-oai |
| Files | spec/yaml/twilio_*.yaml and spec/json/twilio_*.json — one per product |
| Spec version | OpenAPI 3.0.1 per file |
| File count | ~60 per-product files (Accounts, Api v2010, Messaging, Conversations, Flex, Insights, Lookups, and more) |
| License | Public repo, GA per README ("we expect the spec to be accurate") |
| Status | Twilio-maintained, kept in sync with live API validation |
The core "SMS and calls" surface most people mean by "the Twilio API" is spec/yaml/twilio_api_v2010.yaml. Messaging-specific features (like opt-in/opt-out) live in twilio_messaging_v1.yaml. If you need more than one product, you fetch and generate from each file separately, or combine them yourself.
How to fetch it
# Core Twilio API (calls, SMS, accounts)
curl -sL -o twilio-api-v2010.yaml \
https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_api_v2010.yaml
# Messaging-specific endpoints
curl -sL -o twilio-messaging-v1.yaml \
https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_messaging_v1.yaml
Or clone the whole repo and generate from whichever product files you actually use:
gh repo clone twilio/twilio-oai
ls twilio-oai/spec/yaml/ | wc -l # ~60 files
The honest complication: there's no single spec file
This is the real difference from GitHub, Stripe, or OpenAI: Twilio doesn't bundle one file for "the Twilio API." Each product — Accounts, the core v2010 API, Messaging, Conversations, Flex, Insights, Intelligence, Lookups, Marketplace, and dozens more — has its own OpenAPI document, its own info.version, and its own set of schemas, some of which overlap in name but not in shape across products.
Practical effects:
- Figure out which product(s) you actually need before generating anything. Most integrations only touch
twilio_api_v2010.yaml(calls/SMS/accounts) and maybetwilio_messaging_v1.yaml— not all 60. - If you need a client spanning multiple products, you either generate a separate typed client per file (clean, but you end up with several packages) or write a small script to merge the
pathsandcomponents.schemasfrom the files you need into one document before generating — watch for schema name collisions across products when you do. - There's no single "latest" pointer file the way GitHub or Discord provide — you track each product file's version independently.
Generate a TypeScript client locally
Per product file:
npx @openapitools/openapi-generator-cli generate \
-i twilio-api-v2010.yaml \
-g typescript-fetch \
-o ./generated/twilio-core-client
Repeat for each product you need, or script the loop:
for f in twilio-oai/spec/yaml/twilio_{api_v2010,messaging_v1}.yaml; do
name=$(basename "$f" .yaml)
npx @openapitools/openapi-generator-cli generate -i "$f" -g typescript-fetch -o "./generated/$name"
done
For a broader look at picking a generator and judging output quality, see Generate a TypeScript SDK from OpenAPI.
The hosted path
Sourced can take multiple Twilio product spec files and produce one set of hosted docs, a TypeScript SDK preview, a Python SDK preview, and an llms.txt file — without you writing a merge script or maintaining ~60 separate generator invocations. Connect your repo or paste the raw spec URLs for the products you use. Previews are free and unlimited, with up to two hosted noindex docs sites and one hosted MCP server, no credit card required.
When this actually makes sense
- Learning multi-file spec handling. Twilio's split-by-product structure is a realistic example of the "many specs, one API surface" problem you'll hit with other large platform APIs too.
- A language Twilio doesn't officially cover — the official list is Node, Python, Java, C#, PHP, and Ruby; Go, Rust, and others aren't on it.
- A narrow internal wrapper around just Messaging or just Voice, where pulling in the full
twiliopackage (which covers every product) is more than you need. - Agent tooling. Generating an MCP server from a specific Twilio product spec — say, just Messaging — gives an agent scoped, typed tool calls without exposing the entire Twilio surface.
If you're building a Node, Python, Java, C#, PHP, or Ruby app that talks to Twilio, use the official twilio package for that language. It already handles auth, retries, and the multi-product surface as one coherent client — reassembling that yourself from 60 separate OpenAPI files is not a good use of engineering time.
FAQ
Does Twilio have one official OpenAPI spec, or several?
Several. twilio/twilio-oai ships roughly 60 separate OpenAPI 3.0.1 documents, one per product (core API, Messaging, Conversations, Flex, and so on), rather than a single combined file.
Which file is "the" Twilio API spec for calls and SMS?
spec/yaml/twilio_api_v2010.yaml covers the core Voice and SMS surface most integrations use. Messaging-specific features like campaign registration live in a separate twilio_messaging_v1.yaml file.
Can I combine the Twilio spec files into one client?
Yes, but Twilio doesn't provide a merge tool — you'll need to combine the paths and components.schemas from the files you need yourself, watching for schema name collisions between products, or generate a separate client per product file instead.
Should I generate a client instead of using the official twilio package?
Not for Node, Python, Java, C#, PHP, or Ruby — the official SDK already unifies all products into one client with consistent auth and retry handling. Generate from the OpenAPI files for other languages, narrow single-product wrappers, or agent tooling.
Is the Twilio OpenAPI spec OpenAPI 3.0 or 3.1?
3.0.1, across all product files as of this writing.
Can Sourced generate docs from multiple Twilio product specs in one project?
Yes — you can point Sourced at the specific product spec files you use (for example, core API plus Messaging) and get one combined set of hosted docs and SDK previews, rather than maintaining separate generator runs per product.