Справочник API

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

Базовый URL: https://api.paralect.ai/v1

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

Ключ встраивания

Используется для инициализации виджета на клиентской стороне. Публичный ключ встраивается в код виджета для безопасного взаимодействия.

API-ключ

Используется для серверных API-вызовов. Создавайте и управляйте ключами в панели управления. Храните API-ключ в секрете.

Authorization Header Example

curl -X POST "https://api.paralect.ai/v1/api/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your-bot-id",
    "message": "Hello!"
  }'

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

POST/api/chat

Parameter	Type	Required	Description
bot_id	string	Да	Уникальный идентификатор вашего бота.
message	string	Да	Текст сообщения пользователя.
session_id	string	Нет	Опциональный ID сессии для сохранения контекста диалога.
model	string	Нет	Переопределение AI-модели для запроса (например, deepseek-chat, gpt-4o).

Request Example

{
  "bot_id": "bot_abc123",
  "message": "Какой у вас срок возврата?",
  "session_id": "sess_xyz789"
}

Response Example

{
  "id": "msg_123456",
  "reply": "Наш срок возврата — 30 дней с момента покупки.",
  "sources": [
    { "title": "Политика возврата.pdf", "page": 3 }
  ],
  "session_id": "sess_xyz789"
}

POST/api/widget/chat

Версия с ограничением скорости для использования в виджете на клиентской стороне. Поддерживает те же параметры, что и /api/chat, но с более строгими лимитами. Требует Widget Embed Key вместо API Key.

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

GET/api/bots

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

curl -X GET "https://api.paralect.ai/v1/api/bots" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/bots

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

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

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

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

GET/api/documents

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

Parameter	Type	Required	Description
bot_id	string	Да	Фильтр документов по боту.
limit	integer	Нет	Максимальное количество элементов (по умолчанию: 20, макс: 100).
offset	integer	Нет	Смещение для пагинации.

POST/api/documents

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

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

Endpoint	Rate Limit
Widget Chat (/api/widget/chat)	10 запросов/с на IP
Authenticated API (остальные endpoints)	100 запросов/мин на ключ

Коды ошибок

Code	HTTP Status	Description
invalid_request	400	Тело запроса содержит ошибки или отсутствуют обязательные поля.
unauthorized	401	Отсутствуют, недействительны или истекли учётные данные.
bot_not_found	404	Указанный ID бота не существует или был удалён.
rate_limit_exceeded	429	Слишком много запросов. Подождите перед повторной попыткой.
internal_error	500	Непредвиденная ошибка на сервере.

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

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

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

Получить API-ключ Начать бесплатно