Обзор API

Введение в API платформы PraktickAI — базовый URL, аутентификация, лимиты и обработка ошибок. Ранний доступ.

На этой странице

Ранний доступ / предпросмотр. API PraktickAI активно разрабатываются и доступны партнёрам по разработке. Эндпоинты, поля и лимиты могут измениться до общего релиза. Запросите доступ в консоли администратора.

Платформа PraktickAI даёт вашему продукту две ИИ-услуги, опирающиеся на ваши данные, через единый согласованный API: Email API для чтения почтового ящика и создания или автоматической отправки ответов и Agent API для ответов на вопросы из ваших подключённых знаний. Обе используют одну аутентификацию, базовый URL, формат ошибок и лимиты, описанные на этой странице.

Базовый URL

Все запросы отправляются на один базовый URL по HTTPS. Запросы по обычному HTTP отклоняются.

https://api.praktickai.app

API версионируется в пути. Текущая версия — v1, например `https://api.praktickai.app/v1/agent/messages`. Поля добавляются обратно совместимо; несовместимые изменения выходят под новым префиксом версии.

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

Аутентифицируйте каждый запрос Bearer API-ключом в заголовке `Authorization`. Создавайте и ротируйте ключи в консоли администратора в разделе Настройки → API-ключи. Ключи привязаны к одному рабочему пространству.

curl https://api.praktickai.app/v1/agent/messages \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Как сбросить пароль?" }'

API-ключи имеют полный доступ к рабочему пространству. Храните их на сервере, никогда не включайте в код браузера или мобильного приложения и немедленно ротируйте при утечке. Тестовые ключи имеют префикс `pk_test_` и работают только с данными песочницы.

Префикс	Среда	Примечания
pk_live_	Продакшн	Работает с реальными почтовыми ящиками и источниками знаний.
pk_test_	Песочница	Изолированные данные, реальная отправка писем не происходит.

Запросы и ответы

Отправляйте и принимайте JSON. Для запросов с телом задавайте `Content-Type: application/json`. URL коллекций ресурсов оканчиваются слэшем. Метки времени — ISO 8601 в UTC, идентификаторы — непрозрачные строки, чувствительные к регистру.

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

В раннем доступе лимиты применяются к каждому API-ключу. Каждый ответ содержит заголовки лимитов, чтобы вы могли корректно снизить нагрузку.

Заголовок	Описание
X-RateLimit-Limit	Максимум запросов в текущем окне.
X-RateLimit-Remaining	Осталось запросов в текущем окне.
X-RateLimit-Reset	Unix-метка времени сброса окна.

Область	Лимит по умолчанию
Сообщения агента	60 запросов / минуту
Черновик и отправка письма	120 запросов / минуту
Управление знаниями и ящиками	30 запросов / минуту

При превышении лимита API возвращает HTTP 429. Учитывайте заголовок X-RateLimit-Reset и повторяйте с экспоненциальной задержкой. Нужны более высокие лимиты? Напишите в консоли администратора.

Формат ошибок

Ошибки используют стандартные коды HTTP и согласованное тело JSON. Всегда логируйте `request_id` — он позволяет поддержке отследить конкретный вызов.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "Поле 'message' обязательно.",
    "param": "message",
    "request_id": "req_8f2a1c9d4e"
  }
}

Статус	type	Значение
400	invalid_request_error	Запрос сформирован неверно или отсутствует обязательное поле.
401	authentication_error	Отсутствует или неверный API-ключ.
403	permission_error	Ключ действителен, но не имеет прав на это действие.
404	not_found_error	Указанный ресурс не существует.
429	rate_limit_error	Слишком много запросов — снизьте темп и повторите.
500	api_error	Ошибка на нашей стороне. Можно безопасно повторить.

Что дальше

Email API — подключите почтовый ящик и создавайте или автоматически отправляйте обоснованные ответы.
Agent API — отправьте сообщение и получите ответ из ваших знаний с источниками.
Руководство по настройке — подключите Notion, Slack и Google Drive через MCP и разверните агента.

Откройте справочник Email API, справочник Agent API или следуйте руководству по настройке, чтобы подключить первые источники знаний.