# Личный менторинг

Персональный трек, встречи, решения, задания и чат с ментором. Тарифы «С куратором / Лично с Даши».

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `GET` | [`/api/v1/mentoring/track`](/docs/api/mentoring/mentoring-track) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Текущая опубликованная версия личного трека. |
| `GET` | [`/api/v1/mentoring/track/versions`](/docs/api/mentoring/mentoring-versions) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | История опубликованных версий личного трека, включая прошлые публикации; черновики скрыты. id элемента – это versionId для чтения версии. |
| `GET` | [`/api/v1/mentoring/sessions`](/docs/api/mentoring/mentoring-sessions) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Встречи с ментором. |
| `GET` | [`/api/v1/mentoring/sessions/{sessionId}`](/docs/api/mentoring/mentoring-session) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Одна встреча: краткое содержание или очищенный транскрипт. |
| `GET` | [`/api/v1/mentoring/decisions`](/docs/api/mentoring/mentoring-decisions) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Решения со встреч. |
| `GET` | [`/api/v1/mentoring/chat/digests`](/docs/api/mentoring/mentoring-digests) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Ежедневные сводки чата с ментором. |
| `GET` | [`/api/v1/mentoring/chat/messages`](/docs/api/mentoring/mentoring-messages) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Очищенные разрешённые сообщения чата. |
| `GET` | [`/api/v1/mentoring/homework`](/docs/api/mentoring/mentoring-homework) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `mentoring:read` | Задания от ментора. |

Чтение опубликованного личного трека, встреч, решений, заданий и разрешённой очищенной истории чата с ментором. REST и MCP вызывают один и тот же сервис. Идентификатор студента не передаётся: студента определяет авторизованный аккаунт.

**Кто может читать.** Сессия кабинета и Mini App читают собственный менторинг. API-ключу и OAuth-доступу нужен явно выданный `mentoring:read`: другие scopes его не подразумевают, старые ключи и подключения новых прав не получают. Тариф «Лично» должен быть подтверждён не более 15 минут назад. Тариф «Группа» и подарок группового доступа без явного личного доступа получают **403 `MENTORING_NOT_AVAILABLE`** без каких-либо метаданных менторинга. Если проверка доступа временно недоступна, после истечения последней проверки чтение закрывается.

**Что видно.** Только опубликованные и не удалённые материалы с действующим источником и действующими согласиями. Отзыв согласия скрывает данные со следующего запроса. Черновик никогда не скрывает опубликованную версию; если последняя публикация скрыта, отозвана или удалена, объект исчезает целиком, а более старая публикация не возвращается. Неизвестные, чужие, неопубликованные и отозванные идентификаторы встреч и версий дают одинаковый **404 `NOT_FOUND`**. Пустой список – `items: []`, `nextCursor: null`, `updatedAt: null`.

Все ответы – `Cache-Control: private, no-store`. Пути источников, служебные метаданные, доказательства согласий, сырые данные и внутренние заметки не возвращаются. Поиск по курсу и тьютор работают отдельно: `mentoring:read` не даёт тьютору доступ к менторингу.

**Страницы и формат.**

- Списки возвращают `{ items, nextCursor, updatedAt }`; `limit` по умолчанию **20**, максимум **100**. `updatedAt` – время последнего обновления видимого элемента в выборке или null.
- `nextCursor` передавайте без изменений как `cursor` с теми же фильтрами и `limit`. Курсор зашифрован и привязан к аккаунту, фильтрам и снимку данных: подмена, чужой аккаунт, другие фильтры или изменившиеся данные дают **422 `VALIDATION_FAILED`** – начните с первой страницы. Курсоры REST и MCP взаимозаменяемы.
- Встречи сортируются по времени встречи по убыванию, сообщения – по времени, сводки – по дате, остальные списки – по времени обновления; при равенстве – по UUID.
- `from` / `to` чата – даты `YYYY-MM-DD` по Москве включительно, передаются вместе, интервал не больше **31 дня**. По умолчанию – сегодня и 30 предыдущих дней.
- Даты – ISO-8601, неизвестные – null. Длительности и позиции транскрипта – в секундах.
- Элемент содержит `id`, `updatedAt`, `refs` и типизированные `details`. `refs` раскрывают только вид ссылки (`document`, `message`, `segment`, `recording`) и необязательную позицию (`startSeconds`, `endSeconds`, `ordinal`, `revision`).
- Страница транскрипта – по умолчанию 20, максимум **200 сегментов** и обычно **32 KiB** на весь JSON-ответ. Один слишком длинный сегмент возвращается отдельно с `oversizedSegment: true`.

**Общие ошибки:** 401 `UNAUTHENTICATED`; 403 `CREDENTIAL_NOT_ALLOWED`, `INSUFFICIENT_SCOPE`, `MENTORING_NOT_AVAILABLE`; 404 `NOT_FOUND`; 422 `VALIDATION_FAILED`; 429 `RATE_LIMITED`. Формат – общий `{ error: { code, message } }`; инструменты MCP возвращают тот же код в тексте с `isError: true`.
