# Public API (https://docs2.smao.ai/docs/public)



The Public API gives you programmatic access to the resources you manage in
the dashboard, scoped to your own organization. Use it to sync knowledge from
your CMS, mirror contacts from your CRM, trigger outbound calls from your
backend, and pull call transcripts, website chats, and usage numbers into
your own reporting.

Base URL: `https://api2.smao.ai/api/v1`. API operations require a bearer token.
The raw `/openapi.yaml` and `/openapi.json` specifications need no token. See
[Authentication](/docs/authentication). There are no event-delivery webhooks:
poll for state changes such as knowledge sync status or call results.

New here? Start with the [quickstart](/docs/public/quickstart).

## What you can build [#what-you-can-build]

<Cards>
  <Card title="Assistants, voices & prompts" href="/docs/public/assistants/listAssistants">
    Choose a selectable voice, create and configure the assistants that run
    your phone conversations, and manage the reusable prompts that drive them.
  </Card>

  <Card title="Knowledge" href="/docs/public/knowledge-items/createKnowledgeItem">
    Push knowledge-base entries that assistants retrieve from during calls -
    each item is embedded asynchronously for retrieval.
  </Card>

  <Card title="Contacts & groups" href="/docs/public/contacts/listContacts">
    Manage contact records and the groups that organize contacts,
    knowledge items, forwardings, glossary, and pronunciation rules.
  </Card>

  <Card title="Calls & recordings" href="/docs/public/calls/listCalls">
    Read call history with transcripts and analyses, download recordings,
    and trigger outbound calls.
  </Card>

  <Card title="Website chats" href="/docs/public/chats/listChats">
    Read the chats from your website widget - visitor details and the
    messages the visitor saw. Read-only; replies stay in the dashboard Inbox.
  </Card>

  <Card title="Forwardings, glossary, pronunciation, calendars" href="/docs/public/forwardings/listForwardings">
    Tune call behavior: forwarding targets, domain terms, word-level
    pronunciation overrides, and opening-hours calendars.
  </Card>

  <Card title="Statistics" href="/docs/public/statistics/getStatisticsUsage">
    Read-only aggregated call statistics - weekly and monthly usage,
    per-assistant rollups, and last-24h hourly counts.
  </Card>

  <Card title="Tools" href="/docs/public/tools/createTool">
    Custom webhook tools that assistants invoke during calls. Auth secrets
    are encrypted at rest and never returned by the API.
  </Card>
</Cards>

## Conventions [#conventions]

API-defined field names are `snake_case`; caller-defined JSON such as tool
parameters and custom headers keeps the keys you supply. Timestamps are
ISO-8601 UTC, and object IDs are 24-character lowercase hex strings, except
chat IDs, which are the UUIDs the dashboard Inbox shows. List
endpoints use opaque cursor pagination (`limit` + `cursor`,
`meta.next_cursor`). Errors use a single envelope - see
[Errors](/docs/errors). Each API key has default limits of 1,000 reads per
minute, 200 writes per minute, and 60 `POST /calls` per hour; see
[Errors & Rate Limits](/docs/errors).

## API reference [#api-reference]

The full endpoint reference is generated from the OpenAPI spec - see the
sidebar. Each endpoint page includes an interactive playground. The raw spec
(tenant-branded per host) is at
[**SMAO\_API\_URL**/api/v1/openapi.yaml](https://api2.smao.ai/api/v1/openapi.yaml).