Getting Started
Base URLs, environments, and how to make your first request.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.smao.ai |
| Development | https://api2.smao.ai |
Append the base path of the API you are calling:
| API | Base path | Example |
|---|---|---|
| Public API | /api/v1 | https://api.smao.ai/api/v1/ping |
| Distributor API (v2) | /api/distributor/v2 | https://api.smao.ai/api/distributor/v2/organizations |
| Distributor API v1 (supported compatibility) | /api/distributor/v1 | https://api.smao.ai/api/distributor/v1/partners |
Use production unless SMAO has pointed you at the development environment for integration testing. Both environments accept the same requests; API keys are environment-specific.
Choosing the right API
SMAO exposes two separate APIs with separate keys, base paths, and error formats.
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
For marketplaces and distribution partners provisioning SMAO on behalf of their customers: create and manage organizations, assign licenses, and read usage for billing. Keys are issued by SMAO during partner onboarding.
If you are a SMAO customer with a dashboard login, you want the Public API. If you resell SMAO and need to create organizations for third parties, you want the Distributor API.
Both APIs authenticate with a bearer token, but the keys are not interchangeable. See Authentication for how each key 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://api.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
The Distributor API has no /ping endpoint and a different error format. Start at the Distributor quickstart instead.
From here, continue with the Public API overview or jump straight to the Public API quickstart.