REST API

Публичный REST API MAIA. База URL:

https://api.maia-ai.com

Общее

Все запросы требуют аутентификации одним из заголовков:

X-API-Key: maia_ВАШ_КЛЮЧ

или

Authorization: Bearer maia_ВАШ_КЛЮЧ

Ключи создаются в кабинете dashboard.maia-ai.com → раздел «API и MCP» → вкладка «API» → «Создать ключ». Ключ показывается один раз. Подробнее — в разделе Аутентификация.

Права (scopes):

• read — чтение: проекты, звонки, контакты, кампании, база знаний, лидоген, номера.
• write — запись и запуск: исходящие звонки, правка контактов и базы знаний, кампании обзвона, поиск клиентов, привязка номеров.

Все данные строго в рамках владельца ключа: доступны только его проекты и связанные с ними сущности. Бизнес-логика (гейты подписки/баланса, согласие 152-ФЗ, модерация, провижининг) — та же, что в кабинете.

Пагинация

Эндпоинты со списками принимают query-параметры и возвращают объект-обёртку:

{ "items": [ /* … */ ], "total": 128, "limit": 50, "offset": 0 }

Проекты

Список проектов

GET /v1/public/projects — scope read.

Возвращает проекты (агентов), которыми владеет ключ.

curl https://api.maia-ai.com/v1/public/projects \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ"

{
  "projects": [
    { "id": "3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f", "name": "Отдел продаж", "language": "ru" }
  ]
}

Звонки

Запуск исходящего звонка

POST /v1/public/calls — scope write.

Тело запроса:

Проверки перед запуском: владение проектом, активная подписка, баланс ≥ цены минуты (иначе 402), привязанная исходящая линия (иначе 409).

curl -X POST https://api.maia-ai.com/v1/public/calls \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f",
    "phone": "+79991234567",
    "task": "Подтвердить запись на завтра в 15:00",
    "vars": { "client_name": "Иван" }
  }'

Контакты

Единые контакты (те же данные, что в кабинете «Контакты»).

Правка контакта

PATCH /v1/public/contacts/{contact_id} — scope write. Не переданные поля не меняются.

curl -X PATCH https://api.maia-ai.com/v1/public/contacts/a1b2c3d4-1111-2222-3333-444455556666 \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "lead_status": "hot", "tags": ["vip", "callback"] }'

База знаний

Источники знаний проекта. Индексация идёт фоном — статус источника меняется pending → indexing → ready | error; сверяйте его в списке.

Тело POST …/knowledge: type (text | url), title, content (для text), url, crawl (обойти сайт), max_pages (1–50, по умолчанию 15). Файлы — txt/md/csv/json/html до 5 МБ, PDF/DOCX до 20 МБ, через multipart-роут …/knowledge/file.

curl -X POST https://api.maia-ai.com/v1/public/projects/3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f/knowledge \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "type": "url", "url": "https://example.com/faq", "crawl": true, "max_pages": 15 }'

Кампании обзвона

Массовый обзвон списка контактов. Цикл: создать → загрузить контакты → запустить (с согласием) → следить за прогрессом.

params при создании (как в кабинете): timezone, window_start, window_end, concurrency, retries, retry_interval_min, scheduled_start_at. Контакты грузятся JSON-массивом [{phone, name?, vars?}] (E.164-нормализация, дедуп по номеру, mode = append | replace) и только до запуска (иначе 409).

# запуск кампании с подтверждением согласия абонентов
curl -X POST https://api.maia-ai.com/v1/public/campaigns/CAMPAIGN_ID/start \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "consent": true }'

Поиск клиентов (лидоген)

Поиск и обогащение лидов по брифу. Цикл: разобрать бриф (бесплатно) → запустить платный поиск → следить за прогрессом → выгрузить лиды или сразу собрать из них кампанию обзвона.

Тело POST /lead-search: brief_raw, brief_parsed (структура из parse-brief: niche, geo, signals, exclusions, target_leads, queries) и accept_terms (разовая юр-галочка при первом запуске). Списание — по факту обогащённых лидов.

Гейты запуска: активная подписка, модерация брифа (422), непринятые юр-условия (400 без accept_terms при первом запуске), дневной лимит джоб (429), уже есть активная джоба (409), смета против баланса (402).

# 1) бесплатный разбор брифа — покажет смету и доступные источники
curl -X POST https://api.maia-ai.com/v1/public/lead-search/parse-brief \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "brief_raw": "салоны красоты в Казани, 50 лидов" }'

Номера (телефония)

Номера SIP-транков владельца ключа и их привязка к проектам по направлениям (in — входящие, out — исходящие, both — оба). Для звонков и кампаний проекту нужна исходящая линия (out/both).

curl -X POST https://api.maia-ai.com/v1/public/projects/3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f/numbers \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "number": "+74951234567", "direction": "both" }'

Real-time голосовая сессия

POST /v1/public/realtime/session — scope write.

Открывает живую голосовую сессию с агентом проекта по WebRTC: устройство, приложение или SDK ведёт диалог голосом в реальном времени. Ответ (доступ к комнате LiveKit) и примеры подключения (JS, Python, Swift, Kotlin) — на отдельной странице Real-time голос.

Коды ошибок

Полный справочник

Интерактивная OpenAPI-спецификация со всеми полями: API Reference.