Skip to content

Использование REST API ​

REST API предназначен для интеграций с Learning Copilot: автоматического создания учебных планов, обновления задач, записи оценок и работы с материалами.

Адрес и формат запросов ​

В локальном окружении API доступен по адресу:

text
http://app.lvh.me/v1

В другом окружении замените домен на адрес приложения. Все пути ниже указаны относительно /v1. Для JSON-запросов передавайте заголовок:

http
Content-Type: application/json
Accept: application/json

Идентификаторы проектов, этапов, задач, библиотек, папок и файлов имеют формат UUID. Даты передаются в ISO 8601, например 2026-12-31T23:59:59Z.

Полная машинная спецификация API хранится в файле code/backend/docs/swagger.yaml репозитория. Эта страница описывает рекомендуемый порядок использования API и основные сценарии.

Авторизация ​

Bearer-токен ​

Защищённые методы принимают заголовок:

http
Authorization: Bearer <JWT>

API-ключ ​

Для внешней интеграции создайте ключ в разделе API-ключи интерфейса или через методы /access/api-keys. Секрет возвращается только при создании. Передавайте его тем же способом:

http
Authorization: Bearer flk_<secret>

Ключ должен иметь область доступа, соответствующую операции. Методы GET, HEAD и OPTIONS требуют :read, остальные методы — :write.

Доступные домены:

ДоменНазначение
projectsпроекты, этапы, задачи, оценки и политики
storageбиблиотеки, папки и файлы
chatзарезервирован для функций чата

Для создания API-ключей используется JWT-авторизация. Пример запроса:

bash
curl -X POST "http://app.lvh.me/v1/access/api-keys" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Синхронизация учебного плана",
    "scopes": ["projects:read", "projects:write"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Сохраните поле secret из ответа. В списке ключей секрет не возвращается.

Рекомендуемый сценарий работы ​

  1. Создайте проект через POST /projects.
  2. Получите его идентификатор и добавьте этап через POST /projects/{project_id}/stages.
  3. Добавьте задачи через POST /projects/{project_id}/stages/{stage_id}/tasks.
  4. Записывайте результаты обучения через POST /projects/{project_id}/stages/{stage_id}/tasks/{task_id}/assessments.
  5. Получайте готовность задачи и дашборд проекта.
  6. После изменения данных при необходимости запускайте пересчёт готовности.

Проект, этап и задача ​

bash
BASE_URL="http://app.lvh.me/v1"
AUTH="Authorization: Bearer flk_<secret>"

curl -X POST "$BASE_URL/projects" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "name": "Подготовка к экзамену",
    "description": "План подготовки по неделям",
    "priority": "normal",
    "deadline_at": "2026-12-31T23:59:59Z"
  }'

Для создания этапа используйте name, goal, order и необязательный deadline_at:

bash
curl -X POST "$BASE_URL/projects/<project_id>/stages" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "name": "Клеточная биология",
    "goal": "Разобраться в строении клетки",
    "order": 1
  }'

Задача требует outcome, difficulty от 1 до 10, priority и непустой массив blocks. Типы блоков: comprehension, memorization, practice.

bash
curl -X POST "$BASE_URL/projects/<project_id>/stages/<stage_id>/tasks" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "outcome": "Объяснить механизмы клеточного дыхания",
    "difficulty": 6,
    "priority": "normal",
    "blocks": [
      {"type": "comprehension", "weight": 40},
      {"type": "memorization", "weight": 30},
      {"type": "practice", "weight": 30}
    ]
  }'

Оценка и готовность ​

Оценка передаётся в диапазоне от 0 до 100. Обязательные поля — block_type, source, raw_score, normalized_score, confidence_before и confidence_after.

bash
curl -X POST "$BASE_URL/projects/<project_id>/stages/<stage_id>/tasks/<task_id>/assessments" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "block_type": "practice",
    "source": "manual_confirmation",
    "raw_score": 78,
    "normalized_score": 75,
    "confidence_before": 62,
    "confidence_after": 71
  }'

Для чтения данных используйте:

  • GET /projects/{id}/dashboard — показатели проекта;
  • GET /projects/{project_id}/stages/{stage_id}/board — доска этапа;
  • GET /projects/{project_id}/stages/{stage_id}/tasks/{task_id}/readiness — готовность задачи.

Пересчёт запускается отдельными POST-методами:

  • /projects/{id}/readiness/recalculate;
  • /projects/{project_id}/stages/{stage_id}/readiness/recalculate;
  • /projects/{project_id}/stages/{stage_id}/tasks/{task_id}/readiness/recalculate.

Параметры затухания readiness настраиваются отдельно для пользователя или проекта:

  • PATCH /projects/policies/decay — личная настройка пользователя;
  • PATCH /projects/{id}/policies/decay — переопределение для проекта.

Политика содержит периоды полураспада в часах для блоков comprehension, memorization и practice. Все значения должны быть больше нуля. Проектная политика имеет приоритет над личной; без пользовательского переопределения используются значения 120, 72 и 96 часов соответственно.

Библиотеки и файлы ​

Основные методы хранилища:

ДействиеМетод
Создать библиотекуPOST /storage/libraries
Список библиотекGET /storage/libraries
Дерево библиотекиGET /storage/libraries/{id}/tree
Создать папкуPOST /storage/folders
Загрузить небольшой файлPOST /storage/files/upload
Начать multipart-загрузкуPOST /storage/files/init
Получить файлGET /storage/files/{id}/download
Удалить файлDELETE /storage/files/{id}

Для multipart-загрузки порядок такой: init → получение URL частей через /storage/files/{id}/parts → загрузка частей в объектное хранилище → complete. Незавершённую загрузку отменяйте через abort.

Для файла сохраняются имя, размер и MIME-тип как метаданные. API не требует заранее заданный список MIME-типов: если клиент не передал тип, используется application/octet-stream. Имя файла может иметь до 255 символов и не должно содержать управляющие символы или разделители пути / и \; полные имена . и .. запрещены. Максимальный размер файла — 500 МБ.

Управление ключами ​

ДействиеМетод
Создать ключPOST /access/api-keys
Список ключей без секретовGET /access/api-keys
Отозвать ключDELETE /access/api-keys/{id}
Удалить отозванный ключDELETE /access/api-keys/{id}/permanent
Ротировать ключPOST /access/api-keys/{id}/rotate

Ротация возвращает новый секрет. Сохраните его до окончания переходного периода и замените старый секрет в интеграции.

Ответы и ошибки ​

Успешные ответы используют стандартные коды HTTP: 200 для чтения и изменения, 201 для создания, 204 для удаления без тела. Ошибка обычно имеет вид:

json
{
  "error": {
    "kind": "validation",
    "code": "…",
    "message": "…"
  }
}

Основные коды:

HTTPЗначениеДействие
400Некорректный запросПроверьте JSON, обязательные поля и диапазоны
401Нет авторизации или ключ недействителенОбновите JWT или замените ключ
403Недостаточно области доступаДобавьте нужный domain:read или domain:write
404Объект не найденПроверьте UUID и владельца объекта
409Конфликт состоянияПолучите объект заново и повторите действие
413Превышен лимитУменьшите запрос или используйте multipart-загрузку
500Ошибка сервисаПовторите запрос позже

Не повторяйте автоматически необратимые операции без проверки результата. Для повторной отправки оценки или создания объекта сначала убедитесь, что предыдущий запрос не был принят.