Публичный API

Sensei отвечает на вопросы программно через POST /api/v1/ask. Авторизация — стандартный OAuth 2.0 client_credentials grant; токен — JWT (HS256, TTL 1 час). Полная OpenAPI-спека и интерактивный тест-стенд — на странице /api/v1/docs.

Шаг 1. Создать API-клиента

1. Администрирование → API-клиенты → «+ Создать клиента».
2. Задайте имя — оно нужно вам, чтобы в логах различать разные интеграции.
3. Sensei сгенерирует пару client_id / client_secret. Секрет показывается один раз — сохраните.

При утечке секрета — отзовите клиента через тот же раздел и заведите нового. Sensei не хранит секрет в открытом виде, восстановить его нельзя.

Шаг 2. Получить токен

OAuth client_credentials grant: один POST на /oauth/token с HTTP Basic-авторизацией.

curl -X POST https://sensei-data.ru/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

Ответ:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Токен живёт 1 час; запрашивайте новый по мере истечения.

Шаг 3. Задать вопрос

curl -X POST https://sensei-data.ru/api/v1/ask \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "00000000-0000-0000-0000-000000000000",
    "question": "Как добавить нового участника?",
    "answer_mode": "unified"
  }'

• space_id — id пространства, должно принадлежать вашей организации.
• question — вопрос на естественном языке.
• answer_mode (опционально) — per_source или unified. По умолчанию — то, что выбрано на пространстве.

Ответ

{
  "event_id": "...",
  "groups": [
    {
      "name": "Все источники",
      "answer": "Чтобы добавить участника, ... [1]. Подробности — в разделе [2].",
      "sources": [
        { "title": "Приглашения и роли", "slug": "invites" },
        { "title": "Кабинет администратора", "slug": "admin-cabinet" }
      ]
    }
  ],
  "latency_ms": 4321,
  "llm_model": "...",
  "embedding_model": "..."
}

• event_id — id записи в логе вызовов; полезен для дебага.
• groups — список карточек ответа. В unified-режиме всегда одна карточка «Все источники»; в per_source — по карточке на каждый источник.
• answer — текст с цитатами [N], ссылающимися на sources[N-1].

Лимиты и rate-limit

Параметры зависят от тарифа:

• Запросов / 24 ч на организацию (счётчик отдельный от UI-чата).
• Активных клиентов на организацию.
• Sliding-window rate-limit per-client: до 60 запросов в минуту.

При превышении — HTTP 429 с заголовком Retry-After.

Безопасность

• Секрет хранится в форме PBKDF2-хеша; восстановление невозможно.
• Все JWT подписываются стабильным ключом сервиса; периодическая ротация ключа инвалидирует выданные токены (что при TTL 1 ч — нормально).
• Логи вызовов API хранятся отдельно от UI-истории и видны только админу организации.

Что ещё посмотреть

• Режимы ответа — за что отвечает answer_mode.
• Интерактивный Swagger UI: /api/v1/docs.