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 — запись и запуск звонков.

Пагинация

Эндпоинты со списками принимают query-параметры:

Параметр	Тип	По умолчанию	Описание
`limit`	int	—	Сколько записей вернуть
`offset`	int	0	Смещение от начала выборки

Эндпоинты

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

GET /v1/public/projects — scope read.

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

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

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

История звонков

GET /v1/public/calls — scope read.

Параметры: limit, offset.

curl "https://api.maia-ai.com/v1/public/calls?limit=20&offset=0" \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ"

[
  {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "project_id": "3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f",
    "status": "completed",
    "duration": 84,
    "phone": "+79991234567"
  }
]

Детали звонка

GET /v1/public/calls/{call_id} — scope read.

Возвращает статус, длительность, транскрипт и запись звонка.

curl https://api.maia-ai.com/v1/public/calls/c1d2e3f4-5678-90ab-cdef-1234567890ab \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ"

{
  "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
  "project_id": "3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f",
  "status": "completed",
  "duration": 84,
  "phone": "+79991234567",
  "transcript": "...",
  "recording_url": "https://..."
}

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

POST /v1/public/calls — scope write.

Запускает исходящий звонок по проекту.

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

Поле	Тип	Обяз.	Описание
`project_id`	string (uuid)	да	Проект, от имени которого звоним
`phone`	string	да	Номер в формате `+79991234567`
`task`	string	нет	Задача-инструкция для агента
`vars`	object	нет	Произвольные переменные

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

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": "Иван" }
  }'

{
  "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
  "project_id": "3f9a2b10-6c7d-4e88-9f12-0a1b2c3d4e5f",
  "status": "queued",
  "phone": "+79991234567"
}

Контакты

GET /v1/public/contacts — scope read.

Параметры: limit, offset.

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

[
  {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "name": "Иван Петров",
    "phone": "+79991234567"
  }
]

Коды ошибок

Код	Значение
`401`	Ключ не передан или неверный
`402`	Недостаточно средств на балансе
`403`	У ключа нет нужного scope
`404`	Объект не найден
`409`	Нет исходящей SIP-линии

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

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

Аутентификация Real-time голос