Справочник API

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

Базовый URL: /api (относительно) — Дашборд: POST /api/chat (Session cookie, 30/мин на пользователя) · Виджет: POST /api/widget/chat (публично, botId — не ключ, 30/мин на IP)

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

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

Дашборд требует session cookie Better Auth. Никаких API-ключей и заголовков Authorization — просто войдите в аккаунт. Tenant isolation: GET /api/documents?botId=<чужой> → 404/403.

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

Чат виджета — публичный, rate-limited (30/мин на IP, env RATE_LIMIT_WIDGET_PER_MIN). Без аутентификации — botId это публичный идентификатор бота, не ключ. Сервер проверяет активность бота и никогда не отдаёт приватные данные владельца.

Session cookie example (no Authorization header)

curl -X POST "/api/chat" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=<session>" \
  -d '{
    "botId": "your-bot-id",
    "query": "Hello!"
  }'
# Нужна session cookie — сначала войдите через /login. Заголовка Authorization нет.

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

POST/api/chatSession cookie · Dashboard · 30/min per user

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

Request Example — Dashboard

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

Response Example — Dashboard (sources include content)

// Дашборд: POST /api/chat (Session) — включает content чанков
{
  "conversationId": "conv_xyz789",
  "answer": "Наш срок возврата — 30 дней с момента покупки.",
  "sources": [
    { "chunkId": "...", "documentId": "...", "content": "...", "score": 0.92 }
  ],
  "offline": false
}

POST/api/widget/chatPublic · botId ≠ API key · 30/min per IP · SSE

Публичный эндпоинт для виджета. Принимает botId, query, conversationId и visitorId — model не принимается (всегда bot.model). Лимит 30 запросов/мин на IP (env RATE_LIMIT_WIDGET_PER_MIN, default 30). botId — публичный идентификатор, не ключ. Tenant isolation на сервере: приватные данные владельца не возвращаются.

Request Example — Widget (public)

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

Response Example — Widget (sources without content)

// Виджет: POST /api/widget/chat (публично, SSE) — источники без content
{
  "conversationId": "conv_xyz789",
  "answer": "Наш срок возврата — 30 дней с момента покупки.",
  "sources": [
    { "chunkId": "...", "documentId": "...", "score": 0.92 }
  ]
}
// Публичный виджет никогда не возвращает content чанков — только ID + score.
// SSE: { chunk, done } + финальный done { conversationId, messageId, sources }

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

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

Добавление источников знаний боту. Поддерживается: загрузка файлов (PDF, Markdown, DOCX, TXT), извлечение с URL (Website), импорт Sitemap XML или сырой текст. Используйте multipart/form-data для файлов или JSON для URL/текста/sitemap.

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

Endpoint	Rate Limit
Widget Chat (/api/widget/chat)	30 запросов/мин на IP (env RATE_LIMIT_WIDGET_PER_MIN)
Панель управления (/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	Session cookie	Чат дашборда (tenant-isolated). Model override только если разрешено тарифом; sources с content чанков.
POST	/api/widget/chat	Публичный (botId ≠ API key)	Чат виджета — публично, rate-limit 30/мин/IP, tenant-isolated; sources без content (только ID + score), без model override.
GET	/api/bots	Сессия	Список всех ботов в аккаунте.
POST	/api/bots	Сессия	Создание нового бота.
GET	/api/bots/:id	Сессия	Получение бота по ID.
GET	/api/documents	Сессия	Список документов бота.
POST	/api/documents	Сессия	Загрузка документа в бота.

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

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