# REST API

Базовый URL – `https://aos.edgelab.space/api/v1`. Запросы и ответы – JSON (кроме загрузки файлов и аудио, которые передаются сырыми байтами). Даты – ISO-8601, позиции видео – секунды. Неизвестные поля во входящих объектах запрещены.

```bash
curl -sS https://aos.edgelab.space/api/v1/me \
  -H "Authorization: Bearer $AOS_API_KEY"
```

У каждого эндпоинта своя страница: доступ и scope, параметры, тело, ответ, ошибки, лимиты и пример curl. Колонка «Доступ» показывает, какие способы авторизации принимает метод: «API-ключ / OAuth» – значит, метод доступен агенту.

## [Вход и сессии](/docs/api/auth)

Вход по ссылке из бота, Telegram Login, Mini App и паролю; сессии кабинета и выход.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `POST` | [`/api/v1/auth/link/inspect`](/docs/api/auth/auth-link-inspect) | Без авторизации | – | Проверить, в чей кабинет ведёт одноразовая ссылка из бота |
| `POST` | [`/api/v1/auth/link/redeem`](/docs/api/auth/auth-link-redeem) | Без авторизации | – | Однократно обменять ссылку из бота на web-сессию |
| `POST` | [`/api/v1/auth/oidc/start`](/docs/api/auth/auth-oidc-start) | Без авторизации | – | Начать Telegram Login OIDC: URL авторизации и cookie состояния на 10 минут |
| `POST` | [`/api/v1/auth/oidc`](/docs/api/auth/auth-oidc) | Без авторизации | – | Завершить Telegram Login по code и state |
| `POST` | [`/api/v1/auth/tma`](/docs/api/auth/auth-tma) | Без авторизации | – | Проверить подписанную строку Telegram.WebApp.initData и выдать TMA bearer и профиль |
| `POST` | [`/api/v1/auth/tma/refresh`](/docs/api/auth/auth-tma-refresh) | Mini App (TMA) | – | Продлить тот же TMA token: sliding expiry 15 минут, абсолютный срок не более 12 часов |
| `POST` | [`/api/v1/auth/logout`](/docs/api/auth/auth-logout) | Cookie кабинета · Mini App (TMA) | – | Отозвать предъявленную web-сессию или TMA token и остановить связанные активные операции |
| `GET` | [`/api/v1/auth/sessions`](/docs/api/auth/auth-sessions) | Cookie кабинета | – | Список действующих web- и TMA-сессий студента |
| `POST` | [`/api/v1/auth/sessions/revoke-all`](/docs/api/auth/auth-sessions-revoke-all) | Cookie кабинета | – | Отозвать все сессии и TMA tokens студента, включая текущую |
| `POST` | [`/api/v1/auth/password/login`](/docs/api/auth/auth-password-login) | Без авторизации | – | Войти по email и паролю |
| `POST` | [`/api/v1/auth/password/forgot`](/docs/api/auth/auth-password-forgot) | Без авторизации | – | Запросить письмо со ссылкой сброса пароля (30 минут) |
| `POST` | [`/api/v1/auth/password/reset`](/docs/api/auth/auth-password-reset) | Без авторизации | – | Однократно использовать токен письма: задать пароль, погасить ссылки и отозвать все сессии |
| `GET` | [`/api/v1/auth/password`](/docs/api/auth/auth-password-status) | Cookie кабинета · Mini App (TMA) | – | Прочитать статус пароля и почты |
| `POST` | [`/api/v1/auth/password/setup`](/docs/api/auth/auth-password-setup) | Cookie кабинета · Mini App (TMA) | – | Запросить письмо установки/смены email |
| `POST` | [`/api/v1/auth/password/change`](/docs/api/auth/auth-password-change) | Cookie кабинета · Mini App (TMA) | – | Проверить текущий пароль и заменить его |

## [Профиль, анкета, план](/docs/api/profile)

Профиль студента, тариф, анкета курса и персональный план.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `GET` | [`/api/v1/me`](/docs/api/profile/me) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Профиль кабинета, тариф, участие, анкета, готовность плана, доступные функции и лимиты |
| `GET` | [`/api/v1/me/avatar`](/docs/api/profile/me-avatar) | Cookie кабинета · Mini App (TMA) | – | Собственный аватар, JPEG/WebP |
| `GET` | [`/api/v1/onboarding`](/docs/api/profile/onboarding-get) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `profile:read` | Прочитать текущую анкету, шаг, выбранный сетап и статус |
| `PATCH` | [`/api/v1/onboarding`](/docs/api/profile/onboarding-patch) | Cookie кабинета · Mini App (TMA) | – | Автосохранить шаг и частичное обновление ответов только в статусе draft |
| `PUT` | [`/api/v1/onboarding/setup`](/docs/api/profile/onboarding-setup) | Cookie кабинета · Mini App (TMA) | – | Выбрать сетап отдельно от анкеты в любом статусе, не меняя остальные ответы и статус |
| `POST` | [`/api/v1/onboarding/submit`](/docs/api/profile/onboarding-submit) | Cookie кабинета · Mini App (TMA) | – | Проверить полноту анкеты и отправить на разбор |
| `GET` | [`/api/v1/plan`](/docs/api/profile/plan-get) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `profile:read` | Получить состояние персонального плана |

## [Уроки и эфиры](/docs/api/content)

Разделы курса, уроки, эфиры, транскрипты, рекомендация следующего урока и поиск.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `GET` | [`/api/v1/sections`](/docs/api/content/sections) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Разделы курса: тип, номер, название и порядок |
| `GET` | [`/api/v1/lessons`](/docs/api/content/lessons) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Уроки и эфиры, при необходимости фильтр по разделу и kind |
| `GET` | [`/api/v1/lessons/{id}`](/docs/api/content/lesson-get) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Карточка урока/эфира по коду: видео, конспект, таймкоды, промпты, ссылки, задание |
| `GET` | [`/api/v1/lessons/{id}/transcript`](/docs/api/content/lesson-transcript) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Полный transcript по коду, segments с началом в секундах |
| `GET` | [`/api/v1/efirs`](/docs/api/content/efirs) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Эфиры, расписание и записи |
| `GET` | [`/api/v1/next`](/docs/api/content/next) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Рекомендация следующего урока и причина |
| `GET` | [`/api/v1/search`](/docs/api/content/search) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Полнотекстовый поиск по транскриптам и таймкодам уроков/эфиров с применением gating |

## [Прогресс](/docs/api/progress)

Пройденные уроки, позиции видео, домашние задания и отметки шагов плана.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `PUT` | [`/api/v1/plan/milestones`](/docs/api/progress/plan-milestones-put) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `progress:write` | Заменить набор выполненных шагов плана |
| `GET` | [`/api/v1/progress`](/docs/api/progress/progress-get) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `course:read` | Пройденные уроки, позиции проигрывателя в секундах, домашние задания и отметки плана |
| `PUT` | [`/api/v1/progress`](/docs/api/progress/progress-put) | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | `progress:write` | Сохранить прогресс одного урока: хотя бы одно из positionSec, completed, homework |

## [Тьютор и диктовка](/docs/api/tutor)

Единый диалог с AI-тьютором, память тьютора и распознавание голоса. Только из кабинета.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `POST` | [`/api/v1/transcribe`](/docs/api/tutor/transcribe) | Cookie кабинета · Mini App (TMA) | – | Распознать короткую запись, отправив raw audio, не multipart |
| `GET` | [`/api/v1/tutor/messages`](/docs/api/tutor/tutor-messages) | Cookie кабинета · Mini App (TMA) | – | История единого диалога |
| `POST` | [`/api/v1/tutor/messages`](/docs/api/tutor/tutor-send) | Cookie кабинета · Mini App (TMA) | – | Отправить вопрос тьютору и получить конечный JSON, не SSE |
| `GET` | [`/api/v1/tutor/facts`](/docs/api/tutor/tutor-facts) | Cookie кабинета · Mini App (TMA) | – | Факты, которые тьютор помнит о студенте, старые первыми |
| `DELETE` | [`/api/v1/tutor/facts/{id}`](/docs/api/tutor/tutor-fact-delete) | Cookie кабинета · Mini App (TMA) | – | Удалить собственный факт из памяти тьютора |

## [Вложения](/docs/api/files)

Файлы для сообщений тьютору. Только из кабинета.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `POST` | [`/api/v1/files`](/docs/api/files/files-upload) | Cookie кабинета · Mini App (TMA) | – | Загрузить вложение raw bytes, не multipart: тип сверяется с сигнатурой/UTF-8 |
| `GET` | [`/api/v1/files/{id}`](/docs/api/files/files-get) | Cookie кабинета · Mini App (TMA) | – | Скачать собственное вложение |
| `DELETE` | [`/api/v1/files/{id}`](/docs/api/files/files-delete) | Cookie кабинета · Mini App (TMA) | – | Удалить только собственную ещё не прикреплённую загрузку |

## [API-ключи](/docs/api/keys)

Выпуск, ротация и отзыв персональных API-ключей, журнал вызовов. Только из кабинета.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `GET` | [`/api/v1/keys`](/docs/api/keys/keys-list) | Cookie кабинета | – | История персональных API-ключей: active первыми, затем новые |
| `POST` | [`/api/v1/keys`](/docs/api/keys/keys-create) | Cookie кабинета | – | Создать персональный API-ключ на 90 дней |
| `POST` | [`/api/v1/keys/{id}/rotate`](/docs/api/keys/keys-rotate) | Cookie кабинета | – | Атомарно отозвать существующий ключ и выдать новый с тем же именем и scopes на 90 дней |
| `DELETE` | [`/api/v1/keys/{id}`](/docs/api/keys/keys-revoke) | Cookie кабинета | – | Отозвать собственный API-ключ |
| `GET` | [`/api/v1/keys/calls`](/docs/api/keys/keys-calls) | Cookie кабинета | – | Последние вызовы REST/MCP: до 20 на ключ и до 100 суммарно, новые первыми |

## [Личный менторинг](/docs/api/mentoring)

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

| Метод | Путь | Доступ | 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` | Задания от ментора. |

## [Служебные](/docs/api/ops)

Проверка работоспособности.

| Метод | Путь | Доступ | Scope | Назначение |
| --- | --- | --- | --- | --- |
| `GET` | [`/healthz`](/docs/api/ops/healthz) | Без авторизации | – | Проверка работоспособности и SHA установленной версии |

## OAuth и MCP

OAuth-маршруты (`/.well-known/*`, `/oauth/*`) описаны в разделе [OAuth для MCP](/docs/oauth), сервер `/mcp` – в разделе [MCP](/docs/mcp). Служебные маршруты бота и команды курса в публичный API не входят.
