Справочник API

Полная документация Pravia API — интеграция AI-сотрудников, управление документами и настройка ботов программно.

Базовый URL: /api/chat (относительный)

Аутентификация

Панель управления (Cookie сессии)

Запросы из панели управления используют cookie сессии для аутентификации. API-ключ не нужен — просто войдите в аккаунт.

Виджет (публичный)

Эндпоинт чата виджета доступен публично с ограничением скорости. Аутентификация не требуется — только ID бота.

Authorization Header Example

curl -X POST "/api/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "your-bot-id",
    "query": "Hello!"
  }'

Чат-эндпоинты

POST/api/chat

Parameter	Type	Required	Description
botId	string	Да	Уникальный идентификатор вашего бота.
query	string	Да	Текст сообщения пользователя (макс. 2000 символов).
conversationId	string	Нет	Опциональный ID диалога для сохранения контекста.
model	string	Нет	Переопределение модели для запроса (опционально).

Request Example

{
  "botId": "bot_abc123",
  "query": "Какой у вас срок возврата?",
  "conversationId": "conv_xyz789"
}

Response Example

{
  "conversationId": "conv_xyz789",
  "answer": "Наш срок возврата — 30 дней с момента покупки.",
  "sources": [
    { "chunkId": "...", "documentId": "...", "content": "...", "score": 0.92 }
  ],
  "offline": false
}

POST/api/widget/chat

Публичный эндпоинт для виджета. Принимает botId, query, conversationId и visitorId. Ограничение: 10 запросов в минуту на IP. Аутентификация не требуется.

Управление ботами

GET/api/bots

Получение списка всех ваших ботов.

curl -X GET "/api/bots" \
  -H "Content-Type: application/json"

POST/api/bots

Создание нового бота с указанной конфигурацией.

Parameter	Type	Required	Description
name	string	Да	Название бота (1-64 символа).
description	string	Нет	Описание назначения бота.
model	string	Нет	Модель по умолчанию для этого бота.

{
  "name": "Support Bot",
  "description": "Отвечает на вопросы клиентов на основе базы знаний",
  "model": "pravia"
}

Управление документами

GET/api/documents

Получение списка документов для указанного бота.

Parameter	Type	Required	Description
botId	string	Да	Фильтр документов по боту.

POST/api/documents

Загрузка документа в бота. Использует multipart/form-data с полями file и botId. Поддерживаемые форматы: PDF, Markdown (.md, .markdown).

Лимиты запросов

Endpoint	Rate Limit
Widget Chat (/api/widget/chat)	10 запросов/мин на IP
Панель управления (/api/chat, /api/bots, /api/documents)	30 запросов/мин на пользователя

Ответы ошибок

Code	HTTP Status	Description
400	400	Неверный запрос. Возвращает текстовую ошибку: 'botId is required', 'query is required' или 'Query too long'.
401	401	Не авторизовано. Cookie сессии отсутствует или недействительна.
403	403	Доступ запрещён. Лимит биллинга достигнут или нет доступа.
404	404	Не найдено. Бот не существует или неактивен.
503	503	Сервис временно недоступен. Превышен лимит биллинга.
500	500	Внутренняя ошибка сервера.

Сводка эндпоинтов

Method	Endpoint	Auth	Description
POST	/api/chat	Сессия	Отправка сообщения боту и получение ответа AI.
POST	/api/widget/chat	Публичный	Отправка сообщения из виджета с ограничением скорости.
GET	/api/bots	Сессия	Список всех ботов в аккаунте.
POST	/api/bots	Сессия	Создание нового бота.
GET	/api/bots/:id	Сессия	Получение бота по ID.
GET	/api/documents	Сессия	Список документов бота.
POST	/api/documents	Сессия	Загрузка документа в бота.

Готовы к интеграции?

Читать документацию Начать бесплатно