OpenAPI 3.1 spec

The messaging API is described in a machine-readable OpenAPI 3.1 document. Use it to explore the API in Postman or Insomnia, generate a typed client in your language, or give an AI coding assistant an exact description of the endpoints instead of letting it guess.

What the spec contains#

The spec is the customer-facing part of BroadNet's public API specification, the platform the OmniChannels.ai API runs on. It contains every operation a customer token can call, with their parameters, request bodies and examples as BroadNet publishes them. Two groups of operations are left out:

• operations reserved for platform operators, which a customer token cannot call;
• the legacy /websmpp HTTP API, which passes credentials as parameters instead of a Bearer token. For high-volume SMS, use SMPP or the REST endpoints in the spec.

Each tag links to the matching guide on this site, for example the SMS tag to the SMS API page. The guides add what a spec cannot say: sender ID rules, Meta's messaging windows, retry advice and rate limits.

Keep two limits of the spec in mind:

• Responses are thin. Many operations document only the HTTP status, and some return a plain value (POST /sms/sendSms returns the message ID as text). Read the operation's description, and log real responses from your test account before you rely on a field.
• Webhooks are not in the spec. Delivery statuses and inbound messages are pushed to your endpoint; their payloads vary by channel. See Webhooks.

Download it#

curl -sO https://omnichannels.ai/developers/openapi.yaml
curl -sO https://omnichannels.ai/developers/openapi.json

The file is around 1 MB because it carries many request examples. info.version records the spec version; keep the copy you generated code from, and diff it against the published file before you regenerate.

List the operations for one channel with jq:

jq -r '.paths | to_entries[] | .key as $p | .value | to_entries[]
  | select(.value.tags | index("SMS")) | "\(.key | ascii_upcase) \($p)  \(.value.summary)"' openapi.json

Import into Postman or Insomnia#

1. Postman: choose Import, then paste the spec URL or select the downloaded file. Postman creates a collection with one request per operation.
2. Insomnia: choose Import, then From URL (or From File).
3. Set the base URL variable to https://api.broadnet.me if the tool did not take it from the spec.
4. Set authorization on the collection to Bearer Token, with a variable such as {{token}} for your token. Keep the token in a private environment, not in a shared collection.
5. Send POST /sms/identify first. It only analyses a message text, so it confirms that authentication works without sending anything.

Requests sent from these tools are real API calls: a send operation sends a real message and is charged like any other. Use your test credentials and your own verified numbers.

Generate a client or types#

The only official SDK is @broadnet/cpaas-sdk for TypeScript and Node.js, generated from the same specification. For other languages, generate a client with OpenAPI Generator:

# Python
npx @openapitools/openapi-generator-cli generate -i https://omnichannels.ai/developers/openapi.yaml -g python -o omni-python

# Go
npx @openapitools/openapi-generator-cli generate -i https://omnichannels.ai/developers/openapi.yaml -g go -o omni-go

# C# / .NET
npx @openapitools/openapi-generator-cli generate -i https://omnichannels.ai/developers/openapi.yaml -g csharp -o omni-dotnet

npx openapi-typescript https://omnichannels.ai/developers/openapi.yaml -o omni-api.d.ts

Some generators handle OpenAPI 3.1 only partly, so check the generator's notes for your language. Review the generated code for the multipart endpoints (many send operations, including the bulk sends for SMS, WhatsApp, RCS, Messenger and Instagram and the email send, take multipart/form-data), and wrap the few calls you use in your own module so that regenerating the client does not ripple through your code.

Use it with AI coding tools#

An AI coding assistant writes far better integration code when it reads the real request fields instead of recalling them. Give it the spec, or the part you need:

• Point it at the file. Download openapi.yaml into your repository (for example docs/omnichannels-openapi.yaml) and tell the assistant to use it as the source of truth for endpoint paths, fields and enums.
• Give it only what it needs. The full spec is large. Extract the operations you are working on, for example with the jq command above, and paste or save that excerpt.
• Ask for checks against the spec. For example: "Using docs/omnichannels-openapi.yaml, write a function that sends an SMS with POST /sms/sendSms, and list every field you used with its type from the spec."
• Let agents call the API through MCP instead. If you want an assistant to send or look up messages rather than write code, connect it to the MCP server, which exposes the same API as tools. Setup guides: Claude Code, Cursor and n8n.

Never paste your token into a prompt. Keep it in an environment variable such as BROADNET_TOKEN and have generated code read it from there.

Next steps#

• Quickstart: your first SMS end to end.
• SDKs and code samples: the TypeScript SDK and plain HTTP in other languages.
• Errors and limits: status codes, retries and rate limits that the spec does not cover.