# Public API (https://docs.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://api.smao.ai/api/v1`. API operations require a bearer token.
The raw `/openapi.yaml` and `/openapi.json` specifications are public;
retired `/docs` URLs redirect to this site before authentication. 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). Matched operations that reach the rate limiter use
per-key buckets with defaults of 1000 reads/min, 200 writes/min, and 60
`POST /calls` requests/hour. Successful responses include
`X-RateLimit-*` headers; see [Errors](/docs/errors) for exceptions and retry
behavior.

## 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://api.smao.ai/api/v1/openapi.yaml).