Quickstart

From a fresh API key to a live outbound call. All examples use the production base URL https://api.smao.ai/api/v1; development is https://api2.smao.ai/api/v1.

1. Create an API key

In the dashboard, go to Settings → API Keys and create a key. Each key is scoped to your organization and to a single Role, which determines the endpoints it may call. Newly generated keys are ~43-character base64url strings with no prefix; legacy smao_-prefixed keys remain valid. Export it for the examples below:

export SMAO_API_KEY="<your_api_key>"

2. Check connectivity

curl https://api.smao.ai/api/v1/ping \
  -H "Authorization: Bearer $SMAO_API_KEY"

{ "data": { "ok": true, "now": "2026-07-01T12:00:00.000Z" } }

A 401 with error.code = "unauthorized" means the key is missing or invalid — see Errors.

3. Create an assistant

name, language, voice_id, company_name, company_industry, and introduction are required. The platform assigns the phone number.

curl -X POST https://api.smao.ai/api/v1/assistants \
  -H "Authorization: Bearer $SMAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah",
    "language": "en",
    "voice_id": "cgSgspJ2msm6clMCkdW9",
    "company_name": "Example GmbH",
    "company_industry": "Retail",
    "introduction": "Hello, you have reached Example GmbH. How can I help you?"
  }'

The 201 response contains the assistant under data, including its generated id (needed below) and assigned phone_number. See createAssistant for all optional fields.

4. Add knowledge

Knowledge items live in groups: create a knowledges group, add an item, attach the group to your assistant.

curl -X POST https://api.smao.ai/api/v1/groups \
  -H "Authorization: Bearer $SMAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "knowledges", "name": "FAQ" }'

Take data.id from the response and create the item:

curl -X POST https://api.smao.ai/api/v1/knowledge-items \
  -H "Authorization: Bearer $SMAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "<group_id>",
    "name": "Opening hours",
    "text": "We are open Monday to Friday, 9:00 to 18:00."
  }'

Attach the group to the assistant:

curl -X PATCH https://api.smao.ai/api/v1/assistants/<assistant_id> \
  -H "Authorization: Bearer $SMAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledge_group_ids": ["<group_id>"] }'

Embedding is asynchronous: sync_status.state moves pending → syncing → synced (or failed). There are no event webhooks — poll getKnowledgeItem until the item is synced or failed, and apply a client-side timeout so a persistent pending state does not create an endless poll loop.

5. Place an outbound call

Provide exactly one of assistant_id or assistant_phone, and exactly one of to or target_phone. Numbers are E.164 (+ followed by 6–20 digits).

curl -X POST https://api.smao.ai/api/v1/calls \
  -H "Authorization: Bearer $SMAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "<assistant_id>",
    "to": "+491701234999",
    "details": "Follow-up on order 4711."
  }'

{
  "data": {
    "call_id": "65f8fa6f1a9d8e0012ab34cd",
    "assistant_id": "<assistant_id>",
    "assistant_phone": "+491701234567",
    "to": "+491701234999",
    "status": "queued",
    "created_at": "2026-07-01T12:00:00.000Z"
  }
}

POST /calls defaults to a 60 requests/hour bucket per API key and also permits only one outbound call per assistant in any 60-second window. On 429, use Retry-After when present; otherwise wait at least 60 seconds and retry with exponential backoff.

Once the call completes, poll getCall for the transcript and analyses, and getCallRecording for the audio.

6. Where next

The full endpoint reference in the sidebar — every page has an interactive playground.
Errors — error envelope, codes, and retry guidance.
Authentication — key handling and role scoping.