Getting Started
Base URLs and how to make your first request.
Base URL
Use https://api2.smao.ai as the base URL.
Append the base path of the API you are calling:
| API | Base path | Example |
|---|---|---|
| MCP Connector | /mcp | https://api2.smao.ai/mcp |
| Public API | /api/v1 | https://api2.smao.ai/api/v1/ping |
| Distributor API v1 | /api/distributor/v1 | https://api2.smao.ai/api/distributor/v1/partners |
Choosing the right integration
SMAO exposes one AI connector and two separate REST APIs.
MCP Connector
For connecting an AI client directly to a SMAO organization. The client discovers the available tools and can authenticate interactively with OAuth or with an organization API key.
Public API
For SMAO customers automating their own organization: manage assistants and their configuration (prompts, knowledge, glossary, pronunciation, forwardings, calendars, tools), contacts, calls and recordings, and usage statistics. Keys are self-service — create them in the dashboard.
Distributor API v1
For marketplaces and distribution partners provisioning SMAO on behalf of their customers: create partners and customer organizations, assign plans, and read usage and billing. Keys are issued by SMAO during partner onboarding.
If an AI client should operate SMAO for you, use MCP. If your own application needs direct HTTP integration, use the Public API. If you resell SMAO and need to create organizations for third parties, use Distributor API v1.
Both REST APIs authenticate with a bearer token, but the keys are not interchangeable. MCP accepts either Public API organization keys or OAuth. See Authentication for how each credential type works.
Making your first request
Get a Public API key from the dashboard under Settings → API Keys → New key, picking a role that matches the scope you need. Then call GET /ping — it confirms the API is reachable and your key is valid:
curl https://api2.smao.ai/api/v1/ping \
-H "Authorization: Bearer YOUR_API_KEY"Success looks like:
{ "data": { "ok": true, "now": "2026-04-23T00:00:00.000Z" } }A 401 with { "error": { "code": "unauthorized", ... } } means the key is
missing or invalid — check the header and that you are using a Public API key,
not a Distributor key.
Matched Public API operations that pass authentication and the feature gate
carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset
headers. See Errors for exceptions and retry behavior.
Distributor integrators
Distributor API v1 has no /ping endpoint and a different error format. Start
at the Distributor v1 quickstart instead.
From here, continue with the Public API overview or jump straight to the Public API quickstart.