# Getting Started (https://docs2.smao.ai/docs/getting-started)



## Base URL [#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](/docs/mcp)                 | `/mcp`                | `https://api2.smao.ai/mcp`                         |
| Public API                                 | `/api/v1`             | `https://api2.smao.ai/api/v1/ping`                 |
| [Distributor API v1](/docs/distributor-v1) | `/api/distributor/v1` | `https://api2.smao.ai/api/distributor/v1/partners` |

## Choosing the right integration [#choosing-the-right-integration]

SMAO exposes one AI connector and two separate REST APIs.

<Cards>
  <Card title="MCP Connector" href="/docs/mcp">
    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.
  </Card>

  <Card title="Public API" href="/docs/public">
    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.
  </Card>

  <Card title="Distributor API v1" href="/docs/distributor-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.
  </Card>
</Cards>

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](/docs/authentication) for how each credential type works.

## Making your first request [#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`](/docs/public/meta/getPing) — it confirms the API is reachable and your key is valid:

```bash
curl https://api2.smao.ai/api/v1/ping \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success looks like:

```json
{ "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](/docs/errors) for exceptions and retry behavior.

<Callout title="Distributor integrators">
  Distributor API v1 has no `/ping` endpoint and a different error format. Start
  at the [Distributor v1 quickstart](/docs/distributor-v1/quickstart) instead.
</Callout>

From here, continue with the [Public API overview](/docs/public) or jump straight to the [Public API quickstart](/docs/public/quickstart).