← Тех

API Мозг.ру: каталог, прохождение и результаты

API позволит подключить тесты к своему сайту или приложению: подобрать материал, показать вопросы и получить результат. Ваш проект отвечает за интерфейс, Мозг.ру — за содержание теста и расчёт баллов.

Проект интерфейса: все адреса, поля, ID и ответы ниже — иллюстративные примеры будущего API. Домен mozg.example зарезервирован для примеров и не является адресом службы.

Документация API → (заглушка, спецификация готовится)

1. Получите доступ и настройте сервер

Предполагаемый порядок: зарегистрировать проект, указать сайт и сценарий использования, получить разрешённые операции и серверный ключ. Планируем разделять чтение каталога, запуск тестов и доступ к результатам. Доступ к чужим прохождениям ключ не даёт.

Храните ключ в переменной окружения вашего сервера. Не вставляйте его в HTML, JavaScript страницы или публичный репозиторий. Браузер обращается к вашему серверу, а тот — к API Мозг.ру.

MOZG_API_BASE=https://mozg.example/api/v1
MOZG_API_TOKEN=YOUR_SERVER_TOKEN

В примерах используется заголовок Authorization с Bearer-токеном и JSON. Реальные способы выдачи, обновления и отзыва ключей будут описаны в документации после запуска.

2. Найдите тест в каталоге

Запрос списка по тематике и сложности:

curl "https://mozg.example/api/v1/tests?topic=science&difficulty=medium&limit=10" \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Accept: application/json"

Пример ответа. Числа и названия приведены для иллюстрации:

{
  "items": [{
    "id": 123,
    "title": "Как хорошо вы знаете науку?",
    "topic": "science",
    "question_count": 10,
    "estimated_minutes": 7,
    "available": true
  }],
  "next_cursor": null
}

Для следующей страницы предполагается передавать cursor из ответа. Перечень тем должен приходить из отдельного справочника, например GET /topics, а не зависеть от произвольного текста. В партнёрский каталог будут попадать только разрешённые для интеграции материалы.

3. Создайте прохождение

curl -X POST "https://mozg.example/api/v1/attempts" \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-attempt-001" \
  -d '{"test_id":123,"locale":"ru"}'

{
  "attempt_id": "attempt_demo_001",
  "status": "in_progress",
  "question": {
    "id": "q1",
    "text": "Какая планета ближе всего к Солнцу?",
    "type": "single_choice",
    "options": [
      {"id":"a","text":"Меркурий"},
      {"id":"b","text":"Венера"},
      {"id":"c","text":"Марс"}
    ]
  }
}

Правильный ответ не передаётся заранее. Сервер хранит порядок вопросов и правила подсчёта. Если связь оборвалась, повтор создания с тем же ключом идемпотентности должен вернуть то же прохождение; для нового прохождения нужен новый ключ. Это требование к будущей реализации.

4. Отправьте ответ

curl -X POST "https://mozg.example/api/v1/attempts/attempt_demo_001/answers" \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-answer-001" \
  -d '{"question_id":"q1","selected_option_ids":["a"]}'

Ожидаемый ответ содержит подтверждение сохранения, прогресс и следующий вопрос. Для таймера источником истины должно быть серверное время: перезагрузка страницы не должна давать дополнительные минуты. Возможность вернуться к ответу зависит от правил теста.

5. Завершите тест и получите разбор

POST /api/v1/attempts/attempt_demo_001/finish
Authorization: Bearer YOUR_SERVER_TOKEN
Idempotency-Key: example-finish-001

GET /api/v1/attempts/attempt_demo_001/result
Authorization: Bearer YOUR_SERVER_TOKEN

{
  "status": "completed",
  "score": 8,
  "max_score": 10,
  "review": [{
    "question_id": "q1",
    "correct": true,
    "explanation": "Меркурий — ближайшая к Солнцу планета."
  }]
}

Не все тесты сводятся к одному баллу: могут потребоваться шкалы и текстовая интерпретация. Формат результата и доступность правильных ответов должны определяться конкретным тестом. Пример выше описывает обычную викторину.

Ошибки и повторные запросы

В проекте API предусматриваем 401 для отсутствующего или недействительного ключа, 403 для недостаточных прав, 404 для недоступного ресурса, 409 для конфликта состояния, 422 для неверных данных и 429 для превышения лимита. Окончательные коды и схемы будут в спецификации.

{
  "error": {
    "code": "invalid_answer",
    "message": "Выберите один из предложенных вариантов.",
    "request_id": "request_demo_001"
  }
}

Покажите пользователю понятное сообщение и сохраните request_id для диагностики. Ошибки данных не стоит повторять автоматически. При ограничении частоты нужно учитывать Retry-After, если сервер его вернул; сетевые сбои обрабатывать с задержкой и защитой от повторных операций. Числовые квоты ещё не установлены.

API, виджет или MCP?

Виджет подходит для готового блока на странице. API нужен, если вы создаёте свой интерфейс. MCP-коннектор предназначен для работы ИИ-помощника с материалами сайта. Это разные способы интеграции, и каждый требует отдельной реализации.

Открыть документацию API (заглушка) → · Обсудить подключение →