# AgentOS – полная документация > Все страницы https://aos.edgelab.space/docs одним файлом. Индекс: https://aos.edgelab.space/docs/llms.txt. --- # Документация AgentOS AgentOS – кабинет студента курса «AgentOS 3»: уроки и эфиры, транскрипты, анкета, персональный план, прогресс, AI-тьютор и личный менторинг. Всё, что студент видит в кабинете, его агент может читать через **REST API** или **MCP** – от имени студента и только в пределах выданных прав. | Что | Адрес | | --- | --- | | REST API | `https://aos.edgelab.space/api/v1` | | MCP (Streamable HTTP) | `https://aos.edgelab.space/mcp` | | Контракт OpenAPI | [`/docs/openapi.json`](/docs/openapi.json) | | Для ИИ-агентов | [`/docs/llms.txt`](/docs/llms.txt) · [`/docs/llms-full.txt`](/docs/llms-full.txt) | ## Как это устроено Бэкенд AgentOS – для агентов, кабинет – для людей. Один и тот же слой возможностей обслуживает три входа: - **Кабинет** (веб и Telegram Mini App) – вход по ссылке из бота, Telegram Login или паролю, сессия в cookie. - **REST API** – `Authorization: Bearer <ключ>`; персональный API-ключ студент выпускает в кабинете. - **MCP** – те же данные в виде инструментов для Claude, ChatGPT, Claude Code и Codex; авторизация по OAuth или тем же API-ключом. REST и MCP используют общие обработчики, общий журнал вызовов и общие лимиты ключа: инструмент `aos_get_progress` возвращает тот же JSON, что `GET /api/v1/progress`. ## Авторизация - **API-ключ** – `aos3.sk_` и 43 символа base64url, действует 90 дней. Секрет показывается один раз при создании. Права задают scopes. - **OAuth** – для коннекторов Claude.ai и ChatGPT: discovery, динамическая регистрация клиента (DCR), authorization code с PKCE S256. Access token живёт час, refresh token – 30 суток с каждой выдачи (при ротации срок сдвигается). - Bearer-токен передаётся только в заголовке, никогда в query. | Scope | Что открывает | По умолчанию | | --- | --- | --- | | `course:read` | уроки, эфиры, транскрипты, поиск, прогресс, профиль | да | | `profile:read` | анкета и персональный план | да | | `progress:write` | отметки уроков и шагов плана | нет, включается явно | | `tutor:read` | чтение собственной истории тьютора | нет, включается явно | | `mentoring:read` | личный менторинг (тарифы «С куратором / Лично с Даши») | нет, включается явно | Подробнее – [Авторизация и ключи](/docs/auth) и [OAuth для MCP](/docs/oauth). ## Что может агент | Задача | REST | MCP | | --- | --- | --- | | Узнать, кто студент, тариф и права ключа | [`GET /api/v1/me`](/docs/api/profile/me) | `aos_whoami` | | Найти урок или момент в эфире | [`GET /api/v1/search`](/docs/api/content/search) | `aos_search` | | Прочитать урок и транскрипт | [`GET /api/v1/lessons/{id}`](/docs/api/content/lesson-get) | `aos_get_lesson`, `aos_get_transcript` | | Подсказать следующий шаг | [`GET /api/v1/next`](/docs/api/content/next) | `aos_next` | | Отметить урок и шаг плана | [`PUT /api/v1/progress`](/docs/api/progress/progress-put) | `aos_mark_lesson`, `aos_update_plan_milestone` | | Прочитать личный трек и встречи с ментором | [`GET /api/v1/mentoring/track`](/docs/api/mentoring/mentoring-track) | `aos_get_personal_track`, `aos_get_session` | Тьютор, вложения, диктовка и управление ключами доступны только из кабинета – см. [Тарифы и доступ](/docs/access). ## С чего начать 1. [Быстрый старт](/docs/quickstart) – первый запрос за минуту и подключение MCP к Claude, ChatGPT, Claude Code и Codex. 2. [REST API](/docs/api) – все публичные эндпоинты по разделам. 3. [Инструменты MCP](/docs/mcp/tools) – что умеет агент и какие права нужны. 4. [Ошибки](/docs/errors) и [Лимиты](/docs/limits) – как обрабатывать отказы и повторы. ## Документация для ИИ Каждая страница доступна как markdown: добавьте `.md` к адресу (`/docs/quickstart.md`), для обзора – [`/docs/index.md`](/docs/index.md). Кнопка «Скопировать для ИИ» кладёт markdown страницы в буфер, «Открыть в Claude» и «Открыть в ChatGPT» передают ссылку на неё в новый чат. Индекс по стандарту [llms.txt](https://llmstxt.org) – [`/docs/llms.txt`](/docs/llms.txt), вся документация одним файлом – [`/docs/llms-full.txt`](/docs/llms-full.txt). --- # Быстрый старт ## 1. Получите ключ В кабинете откройте раздел «API-ключ» и создайте ключ. По умолчанию у него `course:read` и `profile:read`; запись прогресса (`progress:write`), историю тьютора (`tutor:read`) и личный менторинг (`mentoring:read`) включите отдельно, если они нужны. Секрет вида `aos3.sk_…` показывается один раз – сохраните его в менеджере паролей или переменной окружения: ```bash export AOS_API_KEY=aos3.sk_… ``` Для коннекторов Claude.ai и ChatGPT ключ не нужен: они входят по OAuth (шаг 3). ## 2. Первый запрос Что студенту смотреть дальше – тот же запрос, что показывает кабинет: ```bash curl -s https://aos.edgelab.space/api/v1/next -H "Authorization: Bearer $AOS_API_KEY" ``` Прогресс студента на трёх языках: Прочитайте прогресс студента с API-ключом, которому выдан `course:read`. Во всех трёх примерах используется один endpoint и переменная окружения `AOS_API_KEY` с настоящим ключом; ответ – JSON [Progress](/docs/schemas#progress). Примеры не выполняются автоматически. **curl** ```bash curl --fail-with-body -sS https://aos.edgelab.space/api/v1/progress \ -H "Authorization: Bearer $AOS_API_KEY" ``` **JavaScript · Node.js** ```js const response = await fetch('https://aos.edgelab.space/api/v1/progress', { headers: { Authorization: `Bearer ${process.env.AOS_API_KEY}` }, }); const body = await response.json(); if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(body)}`); console.log(body); ``` **Python · стандартная библиотека** ```python import json import os import urllib.request request = urllib.request.Request( "https://aos.edgelab.space/api/v1/progress", headers={"Authorization": f"Bearer {os.environ['AOS_API_KEY']}"}, ) with urllib.request.urlopen(request) as response: print(json.load(response)) ``` Ответ – JSON. Ошибки приходят в едином формате `{ "error": { "code", "message" } }` – см. [Ошибки](/docs/errors). ## 3. Подключите MCP Адрес сервера – `https://aos.edgelab.space/mcp`, название – `AgentOS`. ### Claude 1. Откройте Claude в браузере или приложении: «Настройки» → «Коннекторы» → «Добавить свой коннектор». 2. Название – `AgentOS`, адрес – `https://aos.edgelab.space/mcp`. Нажмите «Добавить». 3. Claude откроет вход в AgentOS: войдите в кабинет и нажмите «Разрешить». API-ключ не нужен. Если клиент предлагает выбрать способ регистрации, выбирайте автоматическую (DCR). ### ChatGPT 1. Откройте ChatGPT: «Настройки» → «Коннекторы» → добавить свой MCP-сервер. 2. Адрес – `https://aos.edgelab.space/mcp`, авторизация – OAuth с автоматической регистрацией (DCR), без `client_secret`. 3. Войдите в кабинет AgentOS и нажмите «Разрешить», затем включите коннектор в чате. Названия пунктов меню зависят от версии ChatGPT и настроек workspace. ### Claude Code Выполните команду в терминале, вставив свой ключ вместо `aos3.sk_…`. `--scope user` подключает AgentOS во всех проектах: ```bash claude mcp add --scope user --transport http agentos https://aos.edgelab.space/mcp \ --header "Authorization: Bearer aos3.sk_…" ``` Проверьте подключение командой `/mcp` в Claude Code. ### Codex Добавьте блок в `~/.codex/config.toml` – Codex берёт ключ из переменной окружения: ```toml [mcp_servers.agentos] url = "https://aos.edgelab.space/mcp" bearer_token_env_var = "AOS_API_KEY" ``` Добавьте строку с ключом в профиль оболочки (`~/.zshrc` или `~/.bashrc`) и откройте новый терминал: ```bash export AOS_API_KEY=aos3.sk_… ``` Вместо ключа можно войти по OAuth: `codex mcp add agentos --url https://aos.edgelab.space/mcp`, затем `codex mcp login agentos`. ## 4. Спросите агента ```text Через MCP agentos скажи, что мне делать дальше, и пришли ссылку на скилл из последнего эфира ``` Агент вызовет инструменты AgentOS (например, `aos_next`) и ответит с учётом прогресса студента. Полный список – [Инструменты MCP](/docs/mcp/tools). --- # Авторизация и ключи Агенту нужен один из двух bearer-токенов в заголовке `Authorization: Bearer …`: - **персональный API-ключ** `aos3.sk_…` – студент создаёт его в кабинете, срок 90 дней; - **OAuth access token** – его получают MCP-клиенты (Claude.ai, ChatGPT, Codex) после входа и согласия студента, срок 1 час, обновляется refresh-токеном. Оба вида проверяются одинаково: права определяют scopes, лимиты общие для REST и MCP. ## Scopes | Scope | Что открывает | По умолчанию | | --- | --- | --- | | `course:read` | уроки, эфиры, транскрипты, поиск, прогресс, профиль | да | | `profile:read` | анкета и персональный план | да | | `progress:write` | отметки уроков и шагов плана | нет, включается явно | | `tutor:read` | чтение собственной истории тьютора | нет, включается явно | | `mentoring:read` | личный менторинг (тарифы «С куратором / Лично с Даши») | нет, включается явно | `course:read` не открывает анкету и план – для них нужен `profile:read`. `tutor:read` и `mentoring:read` никогда не выдаются по умолчанию и не добавляются к уже выпущенным ключам и подключениям. Не хватает права – ответ 403 `INSUFFICIENT_SCOPE` (в MCP – `isError: true` с тем же кодом). ## Жизненный цикл ключа 1. Создание – в кабинете, после входа не старше 10 минут: [`POST /api/v1/keys`](/docs/api/keys/keys-create). Секрет показывается один раз. 2. Ротация – [`POST /api/v1/keys/{id}/rotate`](/docs/api/keys/keys-rotate): старый ключ отзывается, новый получает то же имя и scopes на 90 дней. 3. Отзыв – [`DELETE /api/v1/keys/{id}`](/docs/api/keys/keys-revoke). 4. Журнал – [`GET /api/v1/keys/calls`](/docs/api/keys/keys-calls): последние вызовы REST и MCP по каждому ключу. Управлять ключами можно только из кабинета: API-ключ и OAuth не могут выпускать ключи. ## Способы авторизации Каждый маршрут содержит назначение, auth, scope, входные поля, ответ, ошибки, лимиты и curl. Имена типов ссылаются на [полные JSON Schema](/docs/schemas): там все вложенные поля, варианты union, required, enum и pattern. `?` в краткой форме – поле необязательно, `| null` – значение может быть null; это разные случаи. Даты – ISO-8601, позиции видео – секунды. Query URL-encoded; числа query проверяются с coercion. Входные strict-object DTO запрещают неизвестные поля. > [!NOTE] > `aos_live_...` – условная маска, **не действующий формат токена**. Заменяйте её реальным секретом: API-ключ / OAuth access token имеют `aos3.sk_` + 43 base64url-символа, TMA – `aos3.tt_` + 43. Cookie `__Host-aos_sess` содержит 43 base64url-символа. Примеры данных синтетические: `student@example.com`, демонстрационный Telegram id, UUID и учебный текст. | Auth | Как передать | Границы | | -------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Кабинет | Cookie `__Host-aos_sess`, Secure / HttpOnly / SameSite=Lax / Path=/ | Сессия: 7 дней бездействия / 30 дней absolute; sensitive endpoints требуют `auth_at` ≤10 минут | | Mini App | `Authorization: Bearer ` | Sliding 15 минут, absolute 12 часов; не может управлять API-ключами | | API-ключ | `Authorization: Bearer aos_live_...` | Личный ключ на 90 дней, scopes из кабинета | | OAuth | Тот же bearer header | Access token 1 час; только там, где разрешён agentKey; [flow и rotation](/docs/oauth) | Поля `mentoring` / `offer` (Me, AgentWhoami, ViewAsStudent) и `mentoringWith` / `offer` (CuratorEnrollment) приходят, только если запрос объявил `X-Aos-Accept: enrollment-labels` (список через запятую, неизвестные значения игнорируются); без заголовка ответ – прежней формы, которую строгий клиент старого контракта (`additionalProperties: false`) принимает. Заголовок меняет только форму ответа, не доступ. Кабинет шлёт его всегда; REST и MCP одинаково. Когда предъявлены и bearer, и cookie, bearer имеет приоритет. Scope проверяется у API-ключей и OAuth-токенов; для сессии/TMA разрешённый метод определяется credential policy, а не строкой scope. `course:read` не даёт доступ к анкете/плану без `profile:read`. `progress:write` разрешает `aos_mark_lesson` и `aos_update_plan_milestone`; для собственной истории тьютора через MCP требуется отдельное opt-in разрешение `tutor:read`; оно не входит в defaults. Для маршрутов с ошибкой `ORIGIN_REJECTED` обязателен точный `Origin: https://aos.edgelab.space`, либо при отсутствии Origin – `Sec-Fetch-Site: same-origin`. Это правило действует и для REST write-вызова API-ключом, если так объявлен маршрут. Query/path не используются для передачи bearer. JSON parser считает пустое тело `{}`, затем применяет DTO; auth/login bodies ограничены 16 KiB. Все ответы API получают `Referrer-Policy: no-referrer`, `nosniff`, CSP, `no-store`; персональные – `private, no-store`, `Vary: Cookie, Authorization`. Исключение: успешный аватар кэшируется приватно до суток. Файлы скачиваются как attachment с sandbox CSP. JSON-RPC и OAuth имеют отдельные форматы ошибок. --- # Тарифы и доступ У курса два тарифа: **«Группа»** и **«Лично»** (личное сопровождение). Тариф студента приходит в поле `tier` (`group` или `personal`) ответов [`GET /api/v1/me`](/docs/api/profile/me) и `aos_whoami`. Любой запрос требует действующего участия в курсе: без него – 403 `NO_ENTITLEMENT`, при временной недоступности проверки – 503 `ENTITLEMENT_UNAVAILABLE`. ## Кто что видит | Раздел | Эндпоинтов / инструментов | «Группа» | «С куратором / Лично с Даши» | API-ключ / OAuth | | --- | --- | --- | --- | --- | | [Вход и сессии](/docs/api/auth) | 15 | да | да | нет, только кабинет | | [Профиль, анкета, план](/docs/api/profile) | 7 | да | да | чтение – да (3 из 7), изменения – только кабинет | | [Уроки и эфиры](/docs/api/content) | 7 | да | да | да | | [Прогресс](/docs/api/progress) | 3 | да | да | да | | [Тьютор и диктовка](/docs/api/tutor) | 5 | да | да | нет, только кабинет | | [Вложения](/docs/api/files) | 3 | да | да | нет, только кабинет | | [API-ключи](/docs/api/keys) | 5 | да | да | нет, только кабинет | | [Личный менторинг](/docs/api/mentoring) | 8 | нет | да | да | | [Служебные](/docs/api/ops) | 1 | да | да | без авторизации | | [Инструменты MCP: курс и прогресс](/docs/mcp/tools) | 14 | да | да | да | | [Инструменты MCP: личный менторинг](/docs/mcp/tools#личный-менторинг) | 8 | нет | да | да | - **Оба тарифа** получают уроки и эфиры, транскрипты и поиск, анкету, персональный план, прогресс и API-ключи; тьютор и диктовка – если включены (`Me.features`). - **«Лично»** дополнительно получает личный менторинг: трек, встречи и их транскрипты, решения, задания и сводки чата с ментором. Студент тарифа «Группа» на эти запросы получает 403 `MENTORING_NOT_AVAILABLE`. - Лимиты тьютора зависят от тарифа и приходят в `Me.limits`. ## Что доступно агенту API-ключ и OAuth открывают только чтение курса и своих данных, отметки прогресса и, по отдельному разрешению, историю тьютора и менторинг. Только из кабинета (cookie или Mini App) работают: - отправка сообщений тьютору, его память и вложения; - диктовка; - выпуск, ротация и отзыв API-ключей, список сессий; - редактирование и отправка анкеты. Закрытые уроки открываются после завершения анкеты: до этого карточка и транскрипт возвращают 403 `ONBOARDING_REQUIRED`. --- # 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 не входят. --- # Вход и сессии Вход по ссылке из бота, 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) | – | Проверить текущий пароль и заменить его | --- # POST /api/v1/auth/link/inspect Проверить, в чей кабинет ведёт одноразовая ссылка из бота. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/link/inspect` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authLinkInspect` | ## Описание Проверить, в чей кабинет ведёт одноразовая ссылка из бота; токен не расходуется. `current` показывает текущий аккаунт, если он отличается; маленький cached avatar может быть встроен в ответ. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [LinkTokenRequest](/docs/schemas#linktokenrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------- | -------- | ----------- | ------------------------ | | `token` | `string` | да | pattern см. полную схему | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [LinkIdentity](/docs/schemas#linkidentity). Краткая форма: `{ target: { displayName: string, username: string | null, avatar: string | null }, current: { displayName: string, username: string | null } | null, expiresAt: string }`. Пример JSON; значения демонстрационные. ```json { "target": { "displayName": "Александр Петров", "username": "alex_petrov", "avatar": "data:image/webp;base64,UklGRkYAAABXRUJQVlA4TDoAAAAvH8AFAA9wROQr+F7BY/6jBWraRpKgL7SFshCu/O9cH4OI/tfh8S53szu90YpKMggPFxsdDYVE4BcD" }, "current": null, "expiresAt": "2026-11-04T09:05:00Z" } ``` **Ошибки:** `422 VALIDATION_FAILED`, `401 LINK_INVALID`, `403 ORIGIN_REJECTED`, `429 RATE_LIMITED`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/link/inspect \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}' ``` ## Ответы по контракту Тело запроса: [LinkTokenRequest](/docs/schemas#linktokenrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [LinkIdentity](/docs/schemas#linkidentity) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, LINK_INVALID, ORIGIN_REJECTED, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authLinkInspect`. --- # POST /api/v1/auth/link/redeem Однократно обменять ссылку из бота на web-сессию. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/link/redeem` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authLinkRedeem` | ## Описание Однократно обменять ссылку из бота на web-сессию. Ссылка действует 5 минут; при гонке или повторе – `LINK_INVALID`. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [LinkTokenRequest](/docs/schemas#linktokenrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------- | -------- | ----------- | ------------------------ | | `token` | `string` | да | pattern см. полную схему | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Me](/docs/schemas#me). Краткая форма: `{ student: Student, flow: "agentos3", tier: Tier, mentoring?: MentoringKind | null, offer?: Offer | null, access: { state: "active" | "grace", checkedAt: string }, onboarding: { status: OnboardingStatus, done: boolean }, planReady: boolean, authKind: "cookie" | "tma", features: { tutor: boolean, agentKeys: boolean, dictation: boolean }, limits: { tutorMessagesPerDay: integer, tutorUsdPerDay: number } }`. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). Пример JSON; значения демонстрационные. ```json { "student": { "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10", "tgId": 100000001, "name": "Александр Петров", "username": "alex_petrov", "avatarUrl": null }, "flow": "agentos3", "tier": "personal", "access": { "state": "active", "checkedAt": "2026-11-04T09:00:00Z" }, "onboarding": { "status": "draft", "done": false }, "planReady": false, "authKind": "cookie", "features": { "tutor": false, "agentKeys": false, "dictation": true }, "limits": { "tutorMessagesPerDay": 100, "tutorUsdPerDay": 2.5 } } ``` **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `401 LINK_INVALID`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/link/redeem \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}' ``` ## Ответы по контракту Тело запроса: [LinkTokenRequest](/docs/schemas#linktokenrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Me](/docs/schemas#me) | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, LINK_INVALID | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authLinkRedeem`. --- # POST /api/v1/auth/oidc/start Начать Telegram Login OIDC: URL авторизации и cookie состояния на 10 минут. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/oidc/start` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authOidcStart` | ## Описание Начать Telegram Login OIDC: URL авторизации и cookie состояния на 10 минут. Если OIDC не настроен, endpoint отвечает `404 NOT_FOUND` до проверки лимита. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [OidcStartResponse](/docs/schemas#oidcstartresponse). Краткая форма: `{ authorizeUrl: string }`. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). Пример JSON; значения демонстрационные. ```json { "authorizeUrl": "https://oauth.telegram.org/auth?response_type=code&client_id=0000000000&redirect_uri=https%3A%2F%2Faos.edgelab.space%2Fauth%2Foidc%2Fcallback&scope=openid%20profile&state=STATE&nonce=NONCE&code_challenge=CHALLENGE&code_challenge_method=S256" } ``` **Ошибки:** `403 ORIGIN_REJECTED`, `429 RATE_LIMITED`, `404 NOT_FOUND`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/oidc/start \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [OidcStartResponse](/docs/schemas#oidcstartresponse) | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: ORIGIN_REJECTED, RATE_LIMITED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authOidcStart`. --- # POST /api/v1/auth/oidc Завершить Telegram Login по code и state. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/oidc` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authOidc` | ## Описание Завершить Telegram Login по code и state. Нужна cookie состояния от `auth/oidc/start`; при отключённом OIDC – 404. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [OidcCallbackRequest](/docs/schemas#oidccallbackrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------- | -------- | ----------- | ------------------------ | | `code` | `string` | да | длина ≥ 1; длина ≤ 512 | | `state` | `string` | да | pattern см. полную схему | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Me](/docs/schemas#me). Краткая форма: `{ student: Student, flow: "agentos3", tier: Tier, mentoring?: MentoringKind | null, offer?: Offer | null, access: { state: "active" | "grace", checkedAt: string }, onboarding: { status: OnboardingStatus, done: boolean }, planReady: boolean, authKind: "cookie" | "tma", features: { tutor: boolean, agentKeys: boolean, dictation: boolean }, limits: { tutorMessagesPerDay: integer, tutorUsdPerDay: number } }`. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). Пример JSON; значения демонстрационные. ```json { "student": { "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10", "tgId": 100000001, "name": "Александр Петров", "username": "alex_petrov", "avatarUrl": null }, "flow": "agentos3", "tier": "personal", "access": { "state": "active", "checkedAt": "2026-11-04T09:00:00Z" }, "onboarding": { "status": "draft", "done": false }, "planReady": false, "authKind": "cookie", "features": { "tutor": false, "agentKeys": false, "dictation": true }, "limits": { "tutorMessagesPerDay": 100, "tutorUsdPerDay": 2.5 } } ``` **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 LOGIN_STATE_INVALID`, `401 LOGIN_INVALID`, `405 METHOD_NOT_ALLOWED`, `404 NOT_FOUND`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "code": "fixture-code-not-real", "state": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/oidc \ --cookie '__Host-aos_ostate=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"code":"fixture-code-not-real","state":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}' ``` ## Ответы по контракту Тело запроса: [OidcCallbackRequest](/docs/schemas#oidccallbackrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Me](/docs/schemas#me) | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, LOGIN_STATE_INVALID, LOGIN_INVALID, METHOD_NOT_ALLOWED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authOidc`. --- # POST /api/v1/auth/tma Проверить подписанную строку Telegram.WebApp.initData и выдать TMA bearer и профиль. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/tma` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authTma` | ## Описание Проверить подписанную строку `Telegram.WebApp.initData` и выдать TMA bearer и профиль. Нельзя подменять её неподписанным JSON пользователя. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [TmaExchangeRequest](/docs/schemas#tmaexchangerequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ---------- | -------- | ----------- | ----------------------- | | `initData` | `string` | да | длина ≥ 1; длина ≤ 8192 | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TmaExchangeResponse](/docs/schemas#tmaexchangeresponse). Краткая форма: `{ session: TmaToken, me: Me }`. Пример JSON; значения демонстрационные. ```json { "session": { "token": "aos3.tt_Zml4dHVyZS1vbmx5LW5vdC1hLXJlYWwtdG1hLXRva2V", "expiresAt": "2026-11-04T09:15:00Z", "absoluteExpiresAt": "2026-11-04T21:00:00Z" }, "me": { "student": { "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10", "tgId": 100000001, "name": "Александр Петров", "username": "alex_petrov", "avatarUrl": null }, "flow": "agentos3", "tier": "personal", "access": { "state": "active", "checkedAt": "2026-11-04T09:00:00Z" }, "onboarding": { "status": "draft", "done": false }, "planReady": false, "authKind": "tma", "features": { "tutor": false, "agentKeys": false, "dictation": true }, "limits": { "tutorMessagesPerDay": 100, "tutorUsdPerDay": 2.5 } } } ``` **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `401 LOGIN_INVALID`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "initData": "query_id=AAF&user=%7B%22id%22%3A100000001%2C%22first_name%22%3A%22Alex%22%7D&auth_date=1793782800&signature=fixture&hash=0000" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/tma \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"initData":"query_id=AAF&user=%7B%22id%22%3A100000001%2C%22first_name%22%3A%22Alex%22%7D&auth_date=1793782800&signature=fixture&hash=0000"}' ``` ## Ответы по контракту Тело запроса: [TmaExchangeRequest](/docs/schemas#tmaexchangerequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TmaExchangeResponse](/docs/schemas#tmaexchangeresponse) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, LOGIN_INVALID | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authTma`. --- # POST /api/v1/auth/tma/refresh Продлить тот же TMA token: sliding expiry 15 минут, абсолютный срок не более 12 часов. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/tma/refresh` | | Доступ | Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authTmaRefresh` | ## Описание Продлить тот же TMA token: sliding expiry 15 минут, абсолютный срок не более 12 часов. Refresh не обновляет время исходной аутентификации. **Auth:** TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TmaToken](/docs/schemas#tmatoken). Краткая форма: `{ token: string, expiresAt: string, absoluteExpiresAt: string }`. Пример JSON; значения демонстрационные. ```json { "token": "aos3.tt_Zml4dHVyZS1vbmx5LW5vdC1hLXJlYWwtdG1hLXRva21", "expiresAt": "2026-11-04T09:30:00Z", "absoluteExpiresAt": "2026-11-04T21:00:00Z" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/tma/refresh \ -H 'Authorization: Bearer TMA_TOKEN_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TmaToken](/docs/schemas#tmatoken) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authTmaRefresh`. --- # POST /api/v1/auth/logout Отозвать предъявленную web-сессию или TMA token и остановить связанные активные операции. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/logout` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authLogout` | ## Описание Отозвать предъявленную web-сессию или TMA token и остановить связанные активные операции. Участие в потоке для logout заново не проверяется. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 204, без тела. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). **Ошибки:** `401 UNAUTHENTICATED`, `403 ORIGIN_REJECTED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/logout \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, ORIGIN_REJECTED, CREDENTIAL_NOT_ALLOWED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authLogout`. --- # GET /api/v1/auth/sessions Список действующих web- и TMA-сессий студента. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/auth/sessions` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authSessions` | ## Описание Список действующих web- и TMA-сессий студента; текущая помечена `current`. **Auth:** сессия кабинета (cookie). **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [SessionList](/docs/schemas#sessionlist). Краткая форма: `{ sessions: (SessionInfo)[] }`. Пример JSON; значения демонстрационные. ```json { "sessions": [ { "id": "7d1c2b3a-0e4f-4a5b-8c6d-1e2f3a4b5c6d", "kind": "cookie", "createdAt": "2026-11-04T09:00:00Z", "lastSeenAt": "2026-11-04T09:20:00Z", "device": "Chrome · macOS", "current": true }, { "id": "8e2d3c4b-1f50-4b6c-9d7e-2f3a4b5c6d7e", "kind": "tma", "createdAt": "2026-11-04T08:40:00Z", "lastSeenAt": null, "device": "Telegram Mini App", "current": false } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/auth/sessions \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [SessionList](/docs/schemas#sessionlist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authSessions`. --- # POST /api/v1/auth/sessions/revoke-all Отозвать все сессии и TMA tokens студента, включая текущую. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/sessions/revoke-all` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | Свежий вход | не старше 10 минут | | operationId | `authSessionsRevokeAll` | ## Описание Отозвать все сессии и TMA tokens студента, включая текущую; очистить cookie. Требует повторного входа, если `auth_at` старше 10 минут. **Auth:** сессия кабинета (cookie). Fresh auth ≤10 минут. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [RevokeAllResponse](/docs/schemas#revokeallresponse). Краткая форма: `{ revoked: integer }`. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). Пример JSON; значения демонстрационные. ```json { "revoked": 2 } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `403 CREDENTIAL_NOT_ALLOWED`, `401 REAUTH_REQUIRED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/sessions/revoke-all \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [RevokeAllResponse](/docs/schemas#revokeallresponse) | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, CREDENTIAL_NOT_ALLOWED, REAUTH_REQUIRED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authSessionsRevokeAll`. --- # POST /api/v1/auth/password/login Войти по email и паролю. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/password/login` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authPasswordLogin` | ## Описание Войти по email и паролю; адрес сравнивается в нижнем регистре. Неверная пара или неизвестный email дают одинаковый `LOGIN_INVALID`. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PasswordLoginRequest](/docs/schemas#passwordloginrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ---------- | -------- | ----------- | ----------------------------------------------------- | | `email` | `string` | да | длина ≤ 254; формат "email"; pattern см. полную схему | | `password` | `string` | да | длина ≥ 1; длина ≤ 128 | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Me](/docs/schemas#me). Краткая форма: `{ student: Student, flow: "agentos3", tier: Tier, mentoring?: MentoringKind | null, offer?: Offer | null, access: { state: "active" | "grace", checkedAt: string }, onboarding: { status: OnboardingStatus, done: boolean }, planReady: boolean, authKind: "cookie" | "tma", features: { tutor: boolean, agentKeys: boolean, dictation: boolean }, limits: { tutorMessagesPerDay: integer, tutorUsdPerDay: number } }`. Устанавливает или очищает cookie входа; login создаёт `__Host-aos_sess` на 30 дней (фактический срок сессии дополнительно проверяет БД). Пример JSON; значения демонстрационные. ```json { "student": { "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10", "tgId": 100000001, "name": "Александр Петров", "username": "alex_petrov", "avatarUrl": null }, "flow": "agentos3", "tier": "personal", "access": { "state": "active", "checkedAt": "2026-11-04T09:00:00Z" }, "onboarding": { "status": "draft", "done": false }, "planReady": false, "authKind": "cookie", "features": { "tutor": false, "agentKeys": false, "dictation": true }, "limits": { "tutorMessagesPerDay": 100, "tutorUsdPerDay": 2.5 } } ``` **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `401 LOGIN_INVALID`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "email": "student@example.com", "password": "Example-password-123" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/login \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"email":"student@example.com","password":"Example-password-123"}' ``` ## Ответы по контракту Тело запроса: [PasswordLoginRequest](/docs/schemas#passwordloginrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Me](/docs/schemas#me) | OK (sets or clears a cookie) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, LOGIN_INVALID | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordLogin`. --- # POST /api/v1/auth/password/forgot Запросить письмо со ссылкой сброса пароля (30 минут). | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/password/forgot` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authPasswordForgot` | ## Описание Запросить письмо со ссылкой сброса пароля (30 минут). После валидации и лимитов всегда 204, независимо от наличия аккаунта; при отключённой почте – 404. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PasswordForgotRequest](/docs/schemas#passwordforgotrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------- | -------- | ----------- | ----------------------------------------------------- | | `email` | `string` | да | длина ≤ 254; формат "email"; pattern см. полную схему | **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `429 RATE_LIMITED`, `404 NOT_FOUND`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "email": "student@example.com" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/forgot \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"email":"student@example.com"}' ``` ## Ответы по контракту Тело запроса: [PasswordForgotRequest](/docs/schemas#passwordforgotrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, RATE_LIMITED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordForgot`. --- # POST /api/v1/auth/password/reset Однократно использовать токен письма: задать пароль, погасить ссылки и отозвать все сессии. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/password/reset` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `authPasswordReset` | ## Описание Однократно использовать токен письма: задать пароль, погасить ссылки и отозвать все сессии. Сам endpoint не выполняет вход; ответ содержит проверенный email. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PasswordResetRequest](/docs/schemas#passwordresetrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ---------- | -------- | ----------- | ------------------------ | | `token` | `string` | да | pattern см. полную схему | | `password` | `string` | да | длина ≥ 8; длина ≤ 128 | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [PasswordResetResponse](/docs/schemas#passwordresetresponse). Краткая форма: `{ email: string }`. Пример JSON; значения демонстрационные. ```json { "email": "alex@example.com" } ``` **Ошибки:** `422 VALIDATION_FAILED`, `403 ORIGIN_REJECTED`, `429 RATE_LIMITED`, `401 LINK_INVALID`; [общие ошибки](/docs/errors). **Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "password": "Example-password-123" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/reset \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","password":"Example-password-123"}' ``` ## Ответы по контракту Тело запроса: [PasswordResetRequest](/docs/schemas#passwordresetrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [PasswordResetResponse](/docs/schemas#passwordresetresponse) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, RATE_LIMITED, LINK_INVALID | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordReset`. --- # GET /api/v1/auth/password Прочитать статус пароля и почты. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/auth/password` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authPasswordStatus` | ## Описание Прочитать статус пароля и почты. `orderEmail` – адрес собственного заказа, `orderEmailMasked` – только маска привязанного заказа; после привязки login email оба поля пусты. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [PasswordStatus](/docs/schemas#passwordstatus). Краткая форма: `{ email: string | null, hasPassword: boolean, mailEnabled: boolean, orderEmail: string | null, orderEmailMasked: string | null }`. Пример JSON; значения демонстрационные. ```json { "email": "alex@example.com", "hasPassword": true, "mailEnabled": true, "orderEmail": null, "orderEmailMasked": null } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/auth/password \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [PasswordStatus](/docs/schemas#passwordstatus) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordStatus`. --- # POST /api/v1/auth/password/setup Запросить письмо установки/смены email. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/password/setup` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authPasswordSetup` | ## Описание Запросить письмо установки/смены email. Ровно одно из `email` и `orderEmail: true`; во втором случае полный адрес заказа разрешается сервером и не возвращается. Нужен Telegram-вход не старше 10 минут либо правильный `currentPassword`, если пароль уже есть. Вход по email-коду не считается свежим Telegram-входом. Успех всегда 204, даже если адрес занят; без mailer – 404. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PasswordSetupRequest](/docs/schemas#passwordsetuprequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ----------------- | -------- | ----------- | ----------------------------------------------------- | | `email` | `string` | нет | длина ≤ 254; формат "email"; pattern см. полную схему | | `orderEmail` | `true` | нет | – | | `currentPassword` | `string` | нет | длина ≥ 1; длина ≤ 128 | **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `401 LOGIN_INVALID`, `401 REAUTH_REQUIRED`, `409 VERSION_CONFLICT`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** 3/10 min/student; защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. **Запрос · JSON** ```json { "email": "student@example.com" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/setup \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"email":"student@example.com"}' ``` ## Ответы по контракту Тело запроса: [PasswordSetupRequest](/docs/schemas#passwordsetuprequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, LOGIN_INVALID, REAUTH_REQUIRED, VERSION_CONFLICT, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordSetup`. --- # POST /api/v1/auth/password/change Проверить текущий пароль и заменить его. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/auth/password/change` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `authPasswordChange` | ## Описание Проверить текущий пароль и заменить его. Текущая сессия остаётся, остальные отзываются. Если пароль ещё не задан – 404. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PasswordChangeRequest](/docs/schemas#passwordchangerequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ----------------- | -------- | ----------- | ---------------------- | | `currentPassword` | `string` | да | длина ≥ 1; длина ≤ 128 | | `newPassword` | `string` | да | длина ≥ 8; длина ≤ 128 | **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `401 LOGIN_INVALID`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** 5/10 min/student. **Запрос · JSON** ```json { "currentPassword": "Example-password-123", "newPassword": "Example-password-123" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/change \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"currentPassword":"Example-password-123","newPassword":"Example-password-123"}' ``` ## Ответы по контракту Тело запроса: [PasswordChangeRequest](/docs/schemas#passwordchangerequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, LOGIN_INVALID, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordChange`. --- # Профиль, анкета, план Профиль студента, тариф, анкета курса и персональный план. | Метод | Путь | Доступ | 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` | Получить состояние персонального плана | --- # GET /api/v1/me Профиль кабинета, тариф, участие, анкета, готовность плана, доступные функции и лимиты. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/me` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `me` | ## Описание Профиль кабинета, тариф, с кем сопровождение (`mentoring`), купленное предложение (`offer`), участие, анкета, готовность плана, доступные функции и лимиты. **Для API-ключа/OAuth ответ сокращён до AgentWhoami**, без student id, Telegram id, username, avatar и лимитов тьютора. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Me](/docs/schemas#me). Краткая форма: `{ student: Student, flow: "agentos3", tier: Tier, mentoring?: MentoringKind | null, offer?: Offer | null, access: { state: "active" | "grace", checkedAt: string }, onboarding: { status: OnboardingStatus, done: boolean }, planReady: boolean, authKind: "cookie" | "tma", features: { tutor: boolean, agentKeys: boolean, dictation: boolean }, limits: { tutorMessagesPerDay: integer, tutorUsdPerDay: number } }`. При agentKey / OAuth вместо Me: [AgentWhoami](/docs/schemas); краткая форма `{ name: string, flow: "agentos3", tier: "group" | "personal", mentoring?: "curator" | "dashi" | null, offer?: "tutoring" | null, onboarding: { status: "draft" | "in_review" | "plan_ready", done: boolean }, planReady: boolean, authKind: "agentKey", keyScopes: ("course:read" | "profile:read" | "progress:write" | "tutor:read" | "mentoring:read")[], keyExpiresAt: string }`. Пример JSON; значения демонстрационные. ```json { "student": { "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10", "tgId": 100000001, "name": "Александр Петров", "username": "alex_petrov", "avatarUrl": "/api/v1/me/avatar?v=3f9a1c0e7b2d4e6f8a0b1c2d3e4f5a6b" }, "flow": "agentos3", "tier": "personal", "access": { "state": "active", "checkedAt": "2026-11-04T09:00:00Z" }, "onboarding": { "status": "draft", "done": false }, "planReady": false, "authKind": "cookie", "features": { "tutor": false, "agentKeys": false, "dictation": true }, "limits": { "tutorMessagesPerDay": 100, "tutorUsdPerDay": 2.5 } } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/me \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Me](/docs/schemas#me) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `me`. --- # GET /api/v1/me/avatar Собственный аватар, JPEG/WebP. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/me/avatar` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `meAvatar` | ## Описание Собственный аватар, JPEG/WebP. `v` – cache-buster; `ETag` + `If-None-Match` дают 304. Успешные ответы используют `Cache-Control: private, max-age=86400`; отсутствие фото – 404. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | ------------------------ | | `v` | `string` | нет | pattern см. полную схему | **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200; бинарное тело `image/jpeg`, `image/webp`. `304` без тела при совпадении `If-None-Match`. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/me/avatar \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | image/jpeg | – | Успех | | 304 | – | – | Not Modified (If-None-Match matched the ETag) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `meAvatar`. --- # GET /api/v1/onboarding Прочитать текущую анкету, шаг, выбранный сетап и статус. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/onboarding` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `profile:read` | | operationId | `onboardingGet` | ## Описание Прочитать текущую анкету, шаг, выбранный сетап и статус; данные принадлежат только вызывающему студенту. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `profile:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Onboarding](/docs/schemas#onboarding). Краткая форма: `{ schemaVersion: 2, status: OnboardingStatus, step: integer, answers: OnboardingDraft, completedAt: string | null }`. Пример JSON; значения демонстрационные. ```json { "schemaVersion": 2, "status": "draft", "step": 3, "answers": { "role": "Основатель бизнеса", "business": "Развиваю студию дизайна, в команде 5 человек", "scenario": [ "Продажи и заявки", "Документы и отчёты", "Другое" ], "scenarioOther": "Разбор входящих брифов" }, "completedAt": null } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/onboarding \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Onboarding](/docs/schemas#onboarding) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `onboardingGet`. --- # PATCH /api/v1/onboarding Автосохранить шаг и частичное обновление ответов только в статусе draft. | Поле | Значение | | --- | --- | | URL | `PATCH https://aos.edgelab.space/api/v1/onboarding` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `onboardingPatch` | ## Описание Автосохранить шаг и частичное обновление ответов только в статусе `draft` (после submit – `422 VALIDATION_FAILED`). Неизвестные поля запрещены; `null` очищает допускающий null ответ. Анкета состоит из 13 шагов; текущая версия схемы 2. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [OnboardingPatchRequest](/docs/schemas#onboardingpatchrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | --------- | ---------------------- | ----------- | ----------- | | `step` | `integer` | да | ≥ 0; ≤ 12 | | `answers` | `OnboardingDraftPatch` | да | – | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Onboarding](/docs/schemas#onboarding). Краткая форма: `{ schemaVersion: 2, status: OnboardingStatus, step: integer, answers: OnboardingDraft, completedAt: string | null }`. Пример JSON; значения демонстрационные. ```json { "schemaVersion": 2, "status": "draft", "step": 5, "answers": { "role": "Основатель бизнеса", "business": "Развиваю студию дизайна, в команде 5 человек", "scenario": [ "Продажи и заявки", "Документы и отчёты", "Другое" ], "scenarioOther": "Разбор входящих брифов", "level": "Пользуюсь ChatGPT/Claude каждый день", "aiTools": [ "ChatGPT", "Claude", "Другое" ], "aiToolsOther": "Midjourney", "about": "" }, "completedAt": null } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. **Запрос · JSON** ```json { "step": 5, "answers": { "aiTools": [ "ChatGPT", "Claude", "Другое" ], "aiToolsOther": "Midjourney", "goal": null, "about": "" } } ``` **Пример · curl** ```bash curl -sS -i -X PATCH https://aos.edgelab.space/api/v1/onboarding \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"step":5,"answers":{"aiTools":["ChatGPT","Claude","Другое"],"aiToolsOther":"Midjourney","goal":null,"about":""}}' ``` ## Ответы по контракту Тело запроса: [OnboardingPatchRequest](/docs/schemas#onboardingpatchrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Onboarding](/docs/schemas#onboarding) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `onboardingPatch`. --- # PUT /api/v1/onboarding/setup Выбрать сетап отдельно от анкеты в любом статусе, не меняя остальные ответы и статус. | Поле | Значение | | --- | --- | | URL | `PUT https://aos.edgelab.space/api/v1/onboarding/setup` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `onboardingSetup` | ## Описание Выбрать сетап отдельно от анкеты в любом статусе, не меняя остальные ответы и статус; допустимые setup ids указаны в схеме. Ответ – обновлённая анкета. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [OnboardingSetupRequest](/docs/schemas#onboardingsetuprequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------- | --------- | ----------- | ----------- | | `setup` | `SetupId` | да | – | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Onboarding](/docs/schemas#onboarding). Краткая форма: `{ schemaVersion: 2, status: OnboardingStatus, step: integer, answers: OnboardingDraft, completedAt: string | null }`. Пример JSON; значения демонстрационные. ```json { "schemaVersion": 2, "status": "in_review", "step": 12, "answers": { "role": "Основатель бизнеса", "business": "Развиваю студию дизайна, в команде 5 человек", "scenario": [ "Продажи и заявки", "Документы и отчёты" ], "level": "Пользуюсь ChatGPT/Claude каждый день", "aiTools": [ "ChatGPT", "Claude" ], "budget": "50_100", "tools": [ "Telegram", "Notion", "Битрикс24", "Другое" ], "toolsOther": "Figma", "time": "3–5 часов в неделю", "hardware": [ "Платный публичный VPN", "Нужна помощь с настройкой" ], "os": "macOS", "goal": "Хочу агента, который разбирает заявки и готовит сводку по продажам", "about": "Работаю из Москвы, удобнее учиться по вечерам.", "socialsPersonal": [ "@studio_founder", "https://vk.com/studio.founder" ], "socialsBusiness": [ "https://t.me/studio_design_channel" ], "website": "https://studio-design.ru", "setup": "hermes" }, "completedAt": "2026-11-04T10:00:00Z" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. **Запрос · JSON** ```json { "setup": "hermes" } ``` **Пример · curl** ```bash curl -sS -i -X PUT https://aos.edgelab.space/api/v1/onboarding/setup \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"setup":"hermes"}' ``` ## Ответы по контракту Тело запроса: [OnboardingSetupRequest](/docs/schemas#onboardingsetuprequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Onboarding](/docs/schemas#onboarding) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `onboardingSetup`. --- # POST /api/v1/onboarding/submit Проверить полноту анкеты и отправить на разбор. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/onboarding/submit` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `onboardingSubmit` | ## Описание Проверить полноту анкеты и отправить на разбор: обязательны role, business, scenario, level, aiTools, budget, tools, time, hardware, os, goal, about; при «Другое» также scenarioOther / aiToolsOther / toolsOther. Socials, website и setup необязательны. Затем состояние `in_review`, уведомление в outbox. Повторная отправка готового состояния идемпотентна. Не хватает полей – `ONBOARDING_INCOMPLETE` с issues. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Onboarding](/docs/schemas#onboarding). Краткая форма: `{ schemaVersion: 2, status: OnboardingStatus, step: integer, answers: OnboardingDraft, completedAt: string | null }`. Пример JSON; значения демонстрационные. ```json { "schemaVersion": 2, "status": "in_review", "step": 12, "answers": { "role": "Основатель бизнеса", "business": "Развиваю студию дизайна, в команде 5 человек", "scenario": [ "Продажи и заявки", "Документы и отчёты" ], "level": "Пользуюсь ChatGPT/Claude каждый день", "aiTools": [ "ChatGPT", "Claude" ], "budget": "50_100", "tools": [ "Telegram", "Notion", "Битрикс24", "Другое" ], "toolsOther": "Figma", "time": "3–5 часов в неделю", "hardware": [ "Платный публичный VPN", "Нужна помощь с настройкой" ], "os": "macOS", "goal": "Хочу агента, который разбирает заявки и готовит сводку по продажам", "about": "Работаю из Москвы, удобнее учиться по вечерам.", "socialsPersonal": [ "@studio_founder", "https://vk.com/studio.founder" ], "socialsBusiness": [ "https://t.me/studio_design_channel" ], "website": "https://studio-design.ru", "setup": "claude" }, "completedAt": "2026-11-04T10:00:00Z" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `422 ONBOARDING_INCOMPLETE`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/onboarding/submit \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Onboarding](/docs/schemas#onboarding) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, ONBOARDING_INCOMPLETE | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `onboardingSubmit`. --- # GET /api/v1/plan Получить состояние персонального плана. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/plan` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `profile:read` | | operationId | `planGet` | ## Описание Получить состояние персонального плана: анкета не завершена, план на разборе или опубликованный контент (`status` / `plan`). **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `profile:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [PlanResponse](/docs/schemas#planresponse). Краткая форма: `{ status: OnboardingStatus, plan: PlanContent | null, version: integer | null, publishedAt: string | null }`. Пример JSON; значения демонстрационные. ```json { "status": "plan_ready", "plan": { "letter": { "title": "Александр, начнём с того, что даст результат.", "paragraphs": [ "Не пытайтесь автоматизировать весь бизнес сразу. Возьмите один процесс — входящие заявки — и доведите его до понятного результата.", "Ниже — ваш маршрут. Идите в своём темпе и приходите на эфиры с вопросами." ] }, "stack": [ { "setup": "hermes", "recommended": true, "note": "Агент работает 24/7 на сервере, разбирает заявки, пока вы заняты." }, { "setup": "claude", "recommended": false, "note": "Ваш выбор из анкеты: подходит для первых шагов, основные шаги плана те же." } ], "dashboards": [ { "name": "Продажи", "value": "24", "label": "заявки за неделю" }, { "name": "Контент", "value": "12", "label": "публикаций в плане" } ], "repos": [ { "title": "dashi-plugin-claude-code", "url": "https://github.com/qwwiwi/dashi-plugin-claude-code", "description": "Готовая основа: Claude Code + Telegram." } ], "skills": [ { "title": "Разбор заявок", "description": "Скилл, который превращает заявку в карточку: клиент, запрос, следующий шаг.", "url": null } ], "project": { "title": "Агент входящих заявок", "description": "Агент читает заявки из Telegram, готовит сводку и ставит задачи в Notion." }, "milestones": [ "Выбрать процесс и запустить первого агента", "Подключить инструменты и память", "Собрать дашборд входящих заявок", "Проверить сценарии и показать проект" ] }, "version": 1, "publishedAt": "2026-11-05T12:00:00Z" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/plan \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [PlanResponse](/docs/schemas#planresponse) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `planGet`. --- # Уроки и эфиры Разделы курса, уроки, эфиры, транскрипты, рекомендация следующего урока и поиск. | Метод | Путь | Доступ | 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 | --- # GET /api/v1/sections Разделы курса: тип, номер, название и порядок. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/sections` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `sections` | ## Описание Разделы курса: тип, номер, название и порядок. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [SectionList](/docs/schemas#sectionlist). Краткая форма: `{ sections: (Section)[] }`. Пример JSON; значения демонстрационные. ```json { "sections": [ { "id": "agentos3.efirs", "kind": "efirs", "number": null, "title": "Эфиры", "lessons": [ { "id": "stream.1", "week": 0, "title": "Приветственный эфир", "minutes": 90, "tools": [ "claude", "mcp" ], "summary": "Знакомство с потоком, как устроены недели и кабинет.", "task": "Придите на эфир с одним вопросом про свой проект.", "kind": "stream", "sectionId": "agentos3.efirs", "gated": false, "locked": false } ] }, { "id": "agentos3.week.1", "kind": "week", "number": 1, "title": "Неделя 1", "lessons": [ { "id": "1.1", "week": 1, "title": "Тестовый урок: как устроен кабинет и тьютор", "minutes": 10, "tools": [ "telegram", "claude" ], "summary": "Где лежат уроки, эфиры и «Мой план». Как задавать вопросы тьютору и подключить своего агента.", "task": "Задайте тьютору вопрос по уроку и проверьте, что ссылка открывает видео на нужной минуте.", "kind": "lesson", "sectionId": "agentos3.week.1", "gated": true, "locked": true } ] } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/sections \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [SectionList](/docs/schemas#sectionlist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `sections`. --- # GET /api/v1/lessons Уроки и эфиры, при необходимости фильтр по разделу и kind. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/lessons` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `lessons` | ## Описание Уроки и эфиры, при необходимости фильтр по разделу и kind. В списке видно `locked`; закрытые уроки не раскрывают детали. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | ----------- | -------------------------------- | ----------- | --------------------- | | `sectionId` | `string` | нет | длина ≥ 1; длина ≤ 64 | | `kind` | `"lesson" \| "tech" \| "stream"` | нет | – | **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [LessonList](/docs/schemas#lessonlist). Краткая форма: `{ lessons: (LessonCard)[] }`. Пример JSON; значения демонстрационные. ```json { "lessons": [ { "id": "stream.1", "week": 0, "title": "Приветственный эфир", "minutes": 90, "tools": [ "claude", "mcp" ], "summary": "Знакомство с потоком, как устроены недели и кабинет.", "task": "Придите на эфир с одним вопросом про свой проект.", "kind": "stream", "sectionId": "agentos3.efirs", "gated": false, "locked": false }, { "id": "1.1", "week": 1, "title": "Тестовый урок: как устроен кабинет и тьютор", "minutes": 10, "tools": [ "telegram", "claude" ], "summary": "Где лежат уроки, эфиры и «Мой план». Как задавать вопросы тьютору и подключить своего агента.", "task": "Задайте тьютору вопрос по уроку и проверьте, что ссылка открывает видео на нужной минуте.", "kind": "lesson", "sectionId": "agentos3.week.1", "gated": true, "locked": true } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i 'https://aos.edgelab.space/api/v1/lessons?kind=lesson' \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [LessonList](/docs/schemas#lessonlist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `lessons`. --- # GET /api/v1/lessons/{id} Карточка урока/эфира по коду: видео, конспект, таймкоды, промпты, ссылки, задание. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/lessons/{id}` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `lessonGet` | ## Описание Карточка урока/эфира по коду: видео, конспект, таймкоды, промпты, ссылки, задание. Закрытый gated-урок требует завершённой анкеты, иначе `ONBOARDING_REQUIRED`. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | ------------------------------------ | | `id` | `string` | да | длина ≤ 32; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [LessonDetail](/docs/schemas#lessondetail). Краткая форма: `{ id: LessonCode, week: integer, title: string, minutes: integer, tools: (string)[], summary: string, task: string, kind: LessonKind, sectionId: string, gated: boolean, locked: boolean, video: LessonVideo, konspekt: string, timecodes: (Timecode)[], prompts: (LessonPrompt)[], links: (LessonLink)[] }`. Пример JSON; значения демонстрационные. ```json { "id": "1.1", "week": 1, "title": "Тестовый урок: как устроен кабинет и тьютор", "minutes": 10, "tools": [ "telegram", "claude" ], "summary": "Где лежат уроки, эфиры и «Мой план». Как задавать вопросы тьютору и подключить своего агента.", "task": "Задайте тьютору вопрос по уроку и проверьте, что ссылка открывает видео на нужной минуте.", "kind": "lesson", "sectionId": "agentos3.week.1", "gated": true, "locked": false, "video": { "provider": "placeholder", "url": null, "durationSec": 600 }, "konspekt": "## Что в этом уроке\n- Где лежат уроки, эфиры и «Мой план».\n- Как задавать вопросы тьютору и как он ссылается на таймкоды.\n- Как подключить своего агента к курсу через MCP.\n", "timecodes": [ { "t": 0, "label": "Вступление", "text": null }, { "t": 130, "label": "Навигация по кабинету", "text": "Слева – уроки по неделям, эфиры открыты всегда." }, { "t": 310, "label": "Тьютор и источники", "text": "Тьютор отвечает по материалам курса и ставит ссылку на минуту урока." }, { "t": 480, "label": "Подключить агента", "text": null } ], "prompts": [ { "title": "Проверка тьютора", "text": "Объясни, что было в тестовом уроке на 05:10" }, { "title": "Проверка MCP", "text": "Через MCP AgentOS получи список уроков и открой 1.1" } ], "links": [ { "title": "AgentOS – поток 3", "url": "https://agentos.edgelab.space/3potok", "description": "Страница потока: расписание и программа" }, { "title": "MCP", "url": "https://modelcontextprotocol.io", "description": null } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `404 NOT_FOUND`, `403 ONBOARDING_REQUIRED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/lessons/1.1 \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [LessonDetail](/docs/schemas#lessondetail) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, NOT_FOUND, ONBOARDING_REQUIRED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `lessonGet`. --- # GET /api/v1/lessons/{id}/transcript Полный transcript по коду, segments с началом в секундах. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/lessons/{id}/transcript` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `lessonTranscript` | ## Описание Полный transcript по коду, `segments` с началом в секундах. Неизвестный или некорректный код – 404; для gated-урока нужна анкета. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | ------------------------------------ | | `id` | `string` | да | длина ≤ 32; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Transcript](/docs/schemas#transcript). Краткая форма: `{ lessonId: LessonCode, segments: (object)[] }`. Пример JSON; значения демонстрационные. ```json { "lessonId": "1.1", "segments": [ { "t": 0, "text": "Привет! Это тестовый урок. Настоящие уроки появятся здесь перед стартом." }, { "t": 130, "text": "Слева – уроки по неделям, эфиры открыты всегда, уроки открываются после анкеты." }, { "t": 310, "text": "Тьютор отвечает по материалам курса и ставит ссылку на минуту урока." }, { "t": 480, "text": "Во вкладке «Подключить агента» – адрес MCP и личный ключ." } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `404 NOT_FOUND`, `403 ONBOARDING_REQUIRED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. ```bash curl -sS -i https://aos.edgelab.space/api/v1/lessons/1.1/transcript \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Transcript](/docs/schemas#transcript) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, NOT_FOUND, ONBOARDING_REQUIRED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `lessonTranscript`. --- # GET /api/v1/efirs Эфиры, расписание и записи. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/efirs` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `efirs` | ## Описание Эфиры, расписание и записи; правила доступа применяются сервером. Расписание задаётся в контенте (`content/agentos3/efirs/*.yaml`, поле `efir.starts_at`, UTC; эфиры идут в 19:00 МСК) и приходит сюда после `sync-content`. Тот же список отдаёт MCP-инструмент `aos_list_efirs`. Для календаря есть статические файлы без авторизации, собранные из того же контента: `/calendar/agentos3-efirs.ics` (всё расписание, можно подписаться) и `/calendar/agentos3-<код>.ics` (один эфир, например `agentos3-stream.2.ics`). **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [EfirList](/docs/schemas#efirlist). Краткая форма: `{ efirs: (Efir)[] }`. Пример JSON; значения демонстрационные. ```json { "efirs": [ { "id": "stream.1", "title": "Приветственный эфир", "day": 1, "minutes": 90, "upcoming": true, "startsAt": "2026-11-02T13:00:00Z", "lessonId": null } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/efirs \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [EfirList](/docs/schemas#efirlist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `efirs`. --- # GET /api/v1/next Рекомендация следующего урока и причина. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/next` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `next` | ## Описание Рекомендация следующего урока и причина: продолжить начатый, следующий, нужна анкета или курс завершён. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [NextLesson](/docs/schemas#nextlesson). Краткая форма: `{ lesson: LessonCard | null, reason: "continue" | "next" | "onboarding" | "done" }`. Пример JSON; значения демонстрационные. ```json { "lesson": { "id": "1.1", "week": 1, "title": "Тестовый урок: как устроен кабинет и тьютор", "minutes": 10, "tools": [ "telegram", "claude" ], "summary": "Где лежат уроки, эфиры и «Мой план». Как задавать вопросы тьютору и подключить своего агента.", "task": "Задайте тьютору вопрос по уроку и проверьте, что ссылка открывает видео на нужной минуте.", "kind": "lesson", "sectionId": "agentos3.week.1", "gated": true, "locked": false }, "reason": "next" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/next \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [NextLesson](/docs/schemas#nextlesson) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `next`. --- # GET /api/v1/search Полнотекстовый поиск по транскриптам и таймкодам уроков/эфиров с применением gating. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/search` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `search` | ## Описание Полнотекстовый поиск по транскриптам и таймкодам уроков/эфиров с применением gating. `q` 2–200 символов после trim, `limit` 1–20 (default 10); результаты содержат источники/таймкоды. Конспекты уроков в поиск не входят. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | ------- | --------- | ----------- | ---------------------- | | `q` | `string` | да | длина ≥ 2; длина ≤ 200 | | `limit` | `integer` | нет | ≥ 1; ≤ 20 | **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [SearchResults](/docs/schemas#searchresults). Краткая форма: `{ query: string, results: (object)[] }`. Пример JSON; значения демонстрационные. ```json { "query": "тьютор", "results": [ { "label": "Урок 1.1 · 05:10", "lesson": "1.1", "seconds": 310, "title": "Тестовый урок: как устроен кабинет и тьютор", "snippet": "Тьютор отвечает по материалам курса и ставит ссылку на минуту урока." } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. ```bash curl -sS -i 'https://aos.edgelab.space/api/v1/search?q=MCP&limit=5' \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [SearchResults](/docs/schemas#searchresults) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `search`. --- # Прогресс Пройденные уроки, позиции видео, домашние задания и отметки шагов плана. | Метод | Путь | Доступ | 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 | --- # PUT /api/v1/plan/milestones Заменить набор выполненных шагов плана. | Поле | Значение | | --- | --- | | URL | `PUT https://aos.edgelab.space/api/v1/plan/milestones` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `progress:write` | | operationId | `planMilestonesPut` | ## Описание Заменить весь набор отметок опубликованного плана. Повтор идемпотентен. Индексы от нуля, уникальны, должны существовать в текущем плане; без опубликованного плана – 404. Отметки привязаны к версии плана: при новой версии набор пустой. `expectedVersion` – положительная версия из GET plan. Несовпадение проверяется под lock публикации до записи → 409 VERSION_CONFLICT, текущий план не меняется. REST и MCP используют общий обработчик. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `progress:write` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [PlanMilestonesUpdateRequest](/docs/schemas#planmilestonesupdaterequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ---------------- | ------------- | ----------- | ----------- | | `expectedVersion` | `integer` | да | > 0; просмотренная версия плана | | `milestonesDone` | `(integer)[]` | да | – | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Progress](/docs/schemas#progress). Краткая форма: `{ completed: (LessonCode)[], positions: Record, homework: Record, milestonesDone: (integer)[] }`. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `409 VERSION_CONFLICT`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Запрос · JSON** ```json { "expectedVersion": 1, "milestonesDone": [ 0, 1 ] } ``` **Пример · curl** ```bash curl -sS -i -X PUT https://aos.edgelab.space/api/v1/plan/milestones \ -H 'Authorization: Bearer aos_live_...' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"milestonesDone":[0,1],"expectedVersion":1}' ``` ## Ответы по контракту Тело запроса: [PlanMilestonesUpdateRequest](/docs/schemas#planmilestonesupdaterequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Progress](/docs/schemas#progress) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, NOT_FOUND, VERSION_CONFLICT | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `planMilestonesPut`. --- # GET /api/v1/progress Пройденные уроки, позиции проигрывателя в секундах, домашние задания и отметки плана. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/progress` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `course:read` | | operationId | `progressGet` | ## Описание Пройденные уроки, позиции проигрывателя в секундах, домашние задания и отметки плана. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `course:read` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Progress](/docs/schemas#progress). Краткая форма: `{ completed: (LessonCode)[], positions: Record, homework: Record, milestonesDone: (integer)[] }`. Пример JSON; значения демонстрационные. ```json { "completed": [ "pre.1" ], "positions": { "1.1": 310 }, "homework": { "pre.1": { "text": "Создал папку проекта и README.", "sent": true } }, "milestonesDone": [] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS -i https://aos.edgelab.space/api/v1/progress \ -H 'Authorization: Bearer aos_live_...' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Progress](/docs/schemas#progress) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `progressGet`. --- # PUT /api/v1/progress Сохранить прогресс одного урока: хотя бы одно из positionSec, completed, homework. | Поле | Значение | | --- | --- | | URL | `PUT https://aos.edgelab.space/api/v1/progress` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `progress:write` | | operationId | `progressPut` | ## Описание Сохранить прогресс одного урока: хотя бы одно из `positionSec`, `completed`, `homework`. `completed: true` ставит отметку и сохраняет первую дату завершения при повторе; `false` и отсутствие поля сохраняют отметку. Завершение монотонно. Для закрытого урока нужна анкета. `positionSec` сохраняется с округлением вниз через `Math.floor`: например, `312.5` → `312`. **Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `progress:write` (для ключей). **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [ProgressUpdateRequest](/docs/schemas#progressupdaterequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------------- | --------------------------------- | ----------- | ------------ | | `lessonId` | `LessonCode` | да | – | | `positionSec` | `number` | нет | ≥ 0; ≤ 86400 | | `completed` | `boolean` | нет | true / false | | `homework` | `{ text: string, sent: boolean }` | нет | – | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Progress](/docs/schemas#progress). Краткая форма: `{ completed: (LessonCode)[], positions: Record, homework: Record, milestonesDone: (integer)[] }`. Пример JSON с целочисленной сохранённой позицией; значения демонстрационные. ```json { "completed": [ "pre.1" ], "positions": { "1.1": 312 }, "homework": { "pre.1": { "text": "Создал папку проекта и README.", "sent": true } }, "milestonesDone": [] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `403 ONBOARDING_REQUIRED`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors). **Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Запрос · JSON** ```json { "lessonId": "1.1", "positionSec": 312.5 } ``` **Пример · curl** ```bash curl -sS -i -X PUT https://aos.edgelab.space/api/v1/progress \ -H 'Authorization: Bearer aos_live_...' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"lessonId":"1.1","positionSec":312.5}' ``` ## Ответы по контракту Тело запроса: [ProgressUpdateRequest](/docs/schemas#progressupdaterequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Progress](/docs/schemas#progress) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, NOT_FOUND, ONBOARDING_REQUIRED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `progressPut`. --- # Тьютор и диктовка Единый диалог с 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) | – | Удалить собственный факт из памяти тьютора | --- # POST /api/v1/transcribe Распознать короткую запись, отправив raw audio, не multipart. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/transcribe` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `transcribe` | ## Описание Распознать короткую запись, отправив raw audio, не multipart. Не более 2 MiB и 120 секунд (технический допуск длительности 3 секунды); чтение тела ограничено 20 секундами. Audio не сохраняется. Без настроенного Groq – 503. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** обязательные raw bytes; `Content-Type`: `audio/webm`, `audio/ogg`, `audio/mp4`. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TranscribeResponse](/docs/schemas#transcriberesponse). Краткая форма: `{ text: string, durationSec: number, remainingSecToday: integer }`. Пример JSON; значения демонстрационные. ```json { "text": "У меня небольшая студия дизайна, хочу агента для заявок.", "durationSec": 6.4, "remainingSecToday": 1793 } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `409 BUSY`, `429 DAILY_LIMIT`, `503 DICTATION_UNAVAILABLE`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** 1 запись одновременно; по умолчанию 1800 учитываемых секунд/день МСК; списание ceil(durationSec), минимум 10 секунд за вызов провайдера. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/transcribe \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: audio/webm' \ --data-binary @example.webm ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TranscribeResponse](/docs/schemas#transcriberesponse) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, BUSY, DAILY_LIMIT, DICTATION_UNAVAILABLE | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `transcribe`. --- # GET /api/v1/tutor/messages История единого диалога. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/tutor/messages` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `tutorMessages` | ## Описание История единого диалога. `before` – cursor из `nextBefore`, новые страницы содержат более старые сообщения; внутри страницы сообщения идут от старых к новым. Default `limit=20`, максимум 50. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | -------- | --------- | ----------- | --------------------------------------- | | `before` | `string` | нет | формат "uuid"; pattern см. полную схему | | `limit` | `integer` | нет | ≥ 1; ≤ 50 | **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TutorMessagesPage](/docs/schemas#tutormessagespage). Краткая форма: `{ messages: (TutorMessage)[], nextBefore: string | null }`. Пример JSON; значения демонстрационные. ```json { "messages": [ { "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a61", "role": "user", "text": "Как подключить MCP к Claude Code?", "sources": [], "citations": [], "error": false, "feedback": null, "attachments": [ { "id": "7a1c2e3f-4b5d-4e6f-8a9b-0c1d2e3f4a51", "name": "скрин ошибки.png", "mime": "image/png", "kind": "image", "size": 184320 } ], "createdAt": "2026-11-06T09:00:00.000Z" }, { "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a62", "role": "assistant", "text": "Подключите сервер командой `claude mcp add` и проверьте его через `/mcp` [1]. Перед запуском пройдите чек-лист [2]. Зачем агенту MCP, коротко описано в каталоге скиллов [3][1].", "sources": [ { "kind": "lesson", "label": "Урок 1.1 · 05:10", "lesson": "1.1", "seconds": 310 }, { "kind": "material", "label": "Материал · Чек-лист подключения MCP", "id": "mcp" }, { "kind": "skill", "label": "Скилл · MCP", "id": "mcp" } ], "citations": [ { "source": 0, "start": 73, "end": 76 }, { "source": 1, "start": 111, "end": 114 }, { "source": 2, "start": 169, "end": 172 }, { "source": 0, "start": 172, "end": 175 } ], "error": false, "feedback": "up", "attachments": [], "createdAt": "2026-11-06T09:00:04.000Z" } ], "nextBefore": null } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i 'https://aos.edgelab.space/api/v1/tutor/messages?limit=20' \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TutorMessagesPage](/docs/schemas#tutormessagespage) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `tutorMessages`. --- # POST /api/v1/tutor/messages Отправить вопрос тьютору и получить конечный JSON, не SSE. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/tutor/messages` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `tutorSend` | ## Описание Отправить вопрос тьютору и получить конечный **JSON, не SSE**. `requestId` – клиентский UUID идемпотентности: повтор не создаёт второй расход. Текст до 4000 символов; текст после trim или хотя бы одно вложение обязательны. До 4 собственных ready uploads, уникальных без учёта регистра, ещё не прикреплённых, моложе 55 минут. В grace-режиме участия отправка запрещена (503); при отключённом тьюторе – `TUTOR_UNAVAILABLE`. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [TutorSendRequest](/docs/schemas#tutorsendrequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | ------------- | ------------ | ----------- | --------------------------------------- | | `requestId` | `string` | да | формат "uuid"; pattern см. полную схему | | `text` | `string` | да | длина ≤ 4000 | | `attachments` | `(string)[]` | нет | элементов ≤ 4 | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TutorSendResponse](/docs/schemas#tutorsendresponse). Краткая форма: `{ userMessage: TutorMessage, reply: TutorMessage, messagesLeftToday: integer }`. Пример JSON; значения демонстрационные. ```json { "userMessage": { "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a61", "role": "user", "text": "Как подключить MCP к Claude Code?", "sources": [], "citations": [], "error": false, "feedback": null, "attachments": [ { "id": "7a1c2e3f-4b5d-4e6f-8a9b-0c1d2e3f4a51", "name": "скрин ошибки.png", "mime": "image/png", "kind": "image", "size": 184320 } ], "createdAt": "2026-11-06T09:00:00.000Z" }, "reply": { "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a62", "role": "assistant", "text": "Подключите сервер командой `claude mcp add` и проверьте его через `/mcp` [1]. Перед запуском пройдите чек-лист [2]. Зачем агенту MCP, коротко описано в каталоге скиллов [3][1].", "sources": [ { "kind": "lesson", "label": "Урок 1.1 · 05:10", "lesson": "1.1", "seconds": 310 }, { "kind": "material", "label": "Материал · Чек-лист подключения MCP", "id": "mcp" }, { "kind": "skill", "label": "Скилл · MCP", "id": "mcp" } ], "citations": [ { "source": 0, "start": 73, "end": 76 }, { "source": 1, "start": 111, "end": 114 }, { "source": 2, "start": 169, "end": 172 }, { "source": 0, "start": 172, "end": 175 } ], "error": false, "feedback": null, "attachments": [], "createdAt": "2026-11-06T09:00:04.000Z" }, "messagesLeftToday": 49 } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `409 BUSY`, `429 DAILY_LIMIT`, `429 GLOBAL_BUDGET`, `503 TUTOR_UNAVAILABLE`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** 1 запуск одновременно на студента; сообщения и USD/день МСК из тарифа (`Me.limits`). Общая оценка изображений сообщения ≤10 000 tokens. **Запрос · JSON** ```json { "requestId": "00000000-0000-4000-8000-000000000001", "text": "Объясни материал урока 1.1" } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/tutor/messages \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"requestId":"00000000-0000-4000-8000-000000000001","text":"Объясни материал урока 1.1"}' ``` ## Ответы по контракту Тело запроса: [TutorSendRequest](/docs/schemas#tutorsendrequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TutorSendResponse](/docs/schemas#tutorsendresponse) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, BUSY, DAILY_LIMIT, GLOBAL_BUDGET, TUTOR_UNAVAILABLE, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `tutorSend`. --- # GET /api/v1/tutor/facts Факты, которые тьютор помнит о студенте, старые первыми. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/tutor/facts` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `tutorFacts` | ## Описание Факты, которые тьютор помнит о студенте, старые первыми. Категории и автор указаны в ответе. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [TutorFacts](/docs/schemas#tutorfacts). Краткая форма: `{ facts: (TutorFact)[] }`. Пример JSON; значения демонстрационные. ```json { "facts": [ { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "fact": "Работает на macOS, ставит Claude Code", "category": "setup", "createdBy": "tutor", "createdAt": "2026-11-06T09:00:04.000Z" } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/tutor/facts \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [TutorFacts](/docs/schemas#tutorfacts) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `tutorFacts`. --- # DELETE /api/v1/tutor/facts/{id} Удалить собственный факт из памяти тьютора. | Поле | Значение | | --- | --- | | URL | `DELETE https://aos.edgelab.space/api/v1/tutor/facts/{id}` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `tutorFactDelete` | ## Описание Удалить собственный факт из памяти тьютора; неизвестный, некорректный или чужой UUID – 404. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | --------------------------------------- | | `id` | `string` | да | формат "uuid"; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X DELETE https://aos.edgelab.space/api/v1/tutor/facts/00000000-0000-4000-8000-000000000001 \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `tutorFactDelete`. --- # Вложения Файлы для сообщений тьютору. Только из кабинета. | Метод | Путь | Доступ | 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) | – | Удалить только собственную ещё не прикреплённую загрузку | --- # POST /api/v1/files Загрузить вложение raw bytes, не multipart: тип сверяется с сигнатурой/UTF-8. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/files` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `filesUpload` | ## Описание Загрузить вложение raw bytes, не multipart: тип сверяется с сигнатурой/UTF-8. До 10 MiB на файл; публичный домен ограничивает тело 4 MB ещё до API. Изображения до 3.75 MiB, сторона ≤4096 px, ≤7 450 000 пикселей; PDF до 20 страниц; извлечённый текст до 20 000 символов (длинный обрезается с `textTruncated=true`). Параллельные загрузки разрешены; сохранённый id передаётся в `TutorSendRequest.attachments`. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | ------ | -------- | ----------- | ---------------------- | | `name` | `string` | нет | длина ≥ 1; длина ≤ 200 | **Body:** обязательные raw bytes; `Content-Type`: `image/png`, `image/jpeg`, `image/webp`, `application/pdf`, `text/plain`, `text/markdown`. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Upload](/docs/schemas#upload). Краткая форма: `{ id: string, name: string, mime: "image/png" | "image/jpeg" | "image/webp" | "application/pdf" | "text/plain" | "text/markdown", kind: "image" | "pdf" | "text", size: integer, width: integer | null, height: integer | null, pages: integer | null, textTruncated: boolean, createdAt: string }`. Пример JSON; значения демонстрационные. ```json { "id": "7a1c2e3f-4b5d-4e6f-8a9b-0c1d2e3f4a51", "name": "скрин ошибки.png", "mime": "image/png", "kind": "image", "size": 184320, "width": 1179, "height": 2556, "pages": null, "textTruncated": false, "createdAt": "2026-11-06T08:59:30.000Z" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `429 DAILY_LIMIT`, `409 STORAGE_LIMIT`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** параллельные загрузки разрешены. Для PDF – до 2 резерваций на студента суммарно в обработке и ожидании. 20 попыток/день МСК, сброс в 00:00 МСК; отказы после резервирования дневной попытки тоже считаются, кроме отказа из-за занятости сервера: такая попытка возвращается в квоту. Превышение собственных 2 PDF-резерваций попытку расходует. Оба вида занятости дают `429 RATE_LIMITED`, сообщение «Сервер занят, попробуйте через минуту», `retryAfterSec: 60`; исчерпанная дневная квота – `429 DAILY_LIMIT`. Лимит хранения – 200 MiB: все неприкреплённые и прикреплённые за последние 30 суток. ```bash curl -sS -i -X POST 'https://aos.edgelab.space/api/v1/files?name=example.txt' \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: text/plain' \ --data-binary @example.txt ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Upload](/docs/schemas#upload) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, DAILY_LIMIT, STORAGE_LIMIT, RATE_LIMITED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `filesUpload`. --- # GET /api/v1/files/{id} Скачать собственное вложение. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/files/{id}` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `filesGet` | ## Описание Скачать только собственное вложение как attachment, с filename / filename*, Content-Length, nosniff и sandbox CSP. Содержимое бинарное либо UTF-8 для текста; чужой/неверный UUID – 404. ETag / 304 этим обработчиком не реализованы. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | --------------------------------------- | | `id` | `string` | да | формат "uuid"; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200; бинарное тело `image/png`, `image/jpeg`, `image/webp`, `application/pdf`, `text/plain`, `text/markdown`. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/files/00000000-0000-4000-8000-000000000001 \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | image/png | – | Успех | | 304 | – | – | Not Modified (If-None-Match matched the ETag) | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `filesGet`. --- # DELETE /api/v1/files/{id} Удалить только собственную ещё не прикреплённую загрузку. | Поле | Значение | | --- | --- | | URL | `DELETE https://aos.edgelab.space/api/v1/files/{id}` | | Доступ | Cookie кабинета · Mini App (TMA) | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `filesDelete` | ## Описание Удалить только собственную ещё не прикреплённую загрузку. Уже использованное в сообщении вложение удалить этим методом нельзя (404). Неиспользованные файлы автоматически очищаются через час. **Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется. **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | --------------------------------------- | | `id` | `string` | да | формат "uuid"; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X DELETE https://aos.edgelab.space/api/v1/files/00000000-0000-4000-8000-000000000001 \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `filesDelete`. --- # API-ключи Выпуск, ротация и отзыв персональных 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 суммарно, новые первыми | --- # GET /api/v1/keys История персональных API-ключей: active первыми, затем новые. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/keys` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `keysList` | ## Описание История персональных API-ключей: active первыми, затем новые; не более 50, только prefix, scopes и метаданные, без secret. OAuth keys исключены из списка. **Auth:** сессия кабинета (cookie). **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [ApiKeyList](/docs/schemas#apikeylist). Краткая форма: `{ keys: (ApiKey)[] }`. Пример JSON; значения демонстрационные. ```json { "keys": [ { "id": "3f6a1c2e-9b4d-4e7f-8a1b-2c3d4e5f6a7b", "name": "MacBook · Claude Code", "prefix": "aos3.sk_EXAMPL", "scopes": [ "course:read", "profile:read" ], "createdAt": "2026-11-10T09:00:00Z", "expiresAt": "2027-02-08T09:00:00Z", "lastUsedAt": "2026-11-10T09:35:00Z", "revokedAt": null, "status": "active" }, { "id": "4a7b2d3f-0c5e-4f80-9b2c-3d4e5f6a7b8c", "name": "Codex", "prefix": "aos3.sk_q-7_Zr", "scopes": [ "course:read", "profile:read", "progress:write" ], "createdAt": "2026-11-09T18:00:00Z", "expiresAt": "2027-02-07T18:00:00Z", "lastUsedAt": null, "revokedAt": "2026-11-10T08:30:00Z", "status": "revoked" }, { "id": "5c9d4f51-2e70-4a12-9d4e-5f6a7b8c9d0e", "name": "Старый ноутбук", "prefix": "aos3.sk_Xy3_9a", "scopes": [ "course:read", "profile:read" ], "createdAt": "2026-08-01T10:00:00Z", "expiresAt": "2026-10-30T10:00:00Z", "lastUsedAt": "2026-10-29T21:14:00Z", "revokedAt": null, "status": "expired" } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/keys \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [ApiKeyList](/docs/schemas#apikeylist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `keysList`. --- # POST /api/v1/keys Создать персональный API-ключ на 90 дней. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/keys` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | Свежий вход | не старше 10 минут | | operationId | `keysCreate` | ## Описание Создать персональный API-ключ на 90 дней. `secret` показывается только в этом ответе. Без `scopes` выдаются `course:read` и `profile:read`; `progress:write` и `tutor:read` включаются отдельно и явно. **Auth:** сессия кабинета (cookie). Fresh auth ≤10 минут. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** `application/json`, [ApiKeyCreateRequest](/docs/schemas#apikeycreaterequest). Все вложенные поля и варианты – по ссылке. | Поле | Тип | Обязательно | Ограничения | | -------- | -------------- | ----------- | ----------------------------------------------- | | `name` | `string` | да | длина ≥ 1; длина ≤ 64; pattern см. полную схему | | `scopes` | `(KeyScope)[]` | нет | элементов ≥ 1; элементов ≤ 4 | **Ответ · статус и структура** **Ответ:** 200 `application/json`, [ApiKeyCreated](/docs/schemas#apikeycreated). Краткая форма: `{ key: ApiKey, secret: string }`. Пример JSON; значения демонстрационные. ```json { "key": { "id": "3f6a1c2e-9b4d-4e7f-8a1b-2c3d4e5f6a7b", "name": "MacBook · Claude Code", "prefix": "aos3.sk_EXAMPL", "scopes": [ "course:read", "profile:read" ], "createdAt": "2026-11-10T09:00:00Z", "expiresAt": "2027-02-08T09:00:00Z", "lastUsedAt": null, "revokedAt": null, "status": "active" }, "secret": "aos3.sk_EXAMPLE_not-a-real-key_0123456789abcdefghij" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`, `401 REAUTH_REQUIRED`, `409 KEY_LIMIT`, `429 KEY_RATE`; [общие ошибки](/docs/errors). **Лимиты:** До 3 активных персональных ключей; до 10 созданий за день МСК (включая rotation). **Запрос · JSON** ```json { "name": "MacBook · Claude Code", "scopes": [ "course:read", "profile:read" ] } ``` **Пример · curl** ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/keys \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' \ -H 'Content-Type: application/json' \ -d '{"name":"MacBook · Claude Code","scopes":["course:read","profile:read"]}' ``` ## Ответы по контракту Тело запроса: [ApiKeyCreateRequest](/docs/schemas#apikeycreaterequest). | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [ApiKeyCreated](/docs/schemas#apikeycreated) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, CREDENTIAL_NOT_ALLOWED, REAUTH_REQUIRED, KEY_LIMIT, KEY_RATE | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `keysCreate`. --- # POST /api/v1/keys/{id}/rotate Атомарно отозвать существующий ключ и выдать новый с тем же именем и scopes на 90 дней. | Поле | Значение | | --- | --- | | URL | `POST https://aos.edgelab.space/api/v1/keys/{id}/rotate` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | Свежий вход | не старше 10 минут | | operationId | `keysRotate` | ## Описание Атомарно отозвать существующий ключ и выдать новый с тем же именем и scopes на 90 дней. Новый `secret` показывается один раз. Истёкший неотозванный ключ также можно заменить. **Auth:** сессия кабинета (cookie). Fresh auth ≤10 минут. **Scope:** не требуется. **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | --------------------------------------- | | `id` | `string` | да | формат "uuid"; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [ApiKeyCreated](/docs/schemas#apikeycreated). Краткая форма: `{ key: ApiKey, secret: string }`. Пример JSON; значения демонстрационные. ```json { "key": { "id": "5b8c3e4a-1d6f-4a91-8c3d-4e5f6a7b8c9d", "name": "MacBook · Claude Code", "prefix": "aos3.sk_EXAMPL", "scopes": [ "course:read", "profile:read" ], "createdAt": "2027-02-01T10:00:00Z", "expiresAt": "2027-05-02T10:00:00Z", "lastUsedAt": null, "revokedAt": null, "status": "active" }, "secret": "aos3.sk_EXAMPLE_rotated-not-real_0123456789abcdefgh" } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`, `401 REAUTH_REQUIRED`, `404 NOT_FOUND`, `409 KEY_LIMIT`, `429 KEY_RATE`; [общие ошибки](/docs/errors). **Лимиты:** Те же ограничения создания: до 3 активных и 10 созданий/день МСК; заменяемый ключ не занимает дополнительный слот. ```bash curl -sS -i -X POST https://aos.edgelab.space/api/v1/keys/00000000-0000-4000-8000-000000000001/rotate \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [ApiKeyCreated](/docs/schemas#apikeycreated) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, CREDENTIAL_NOT_ALLOWED, REAUTH_REQUIRED, NOT_FOUND, KEY_LIMIT, KEY_RATE | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `keysRotate`. --- # DELETE /api/v1/keys/{id} Отозвать собственный API-ключ. | Поле | Значение | | --- | --- | | URL | `DELETE https://aos.edgelab.space/api/v1/keys/{id}` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | Свежий вход | не старше 10 минут | | operationId | `keysRevoke` | ## Описание Отозвать собственный API-ключ. Повторный отзыв, неизвестный или чужой id – `NOT_FOUND`. **Auth:** сессия кабинета (cookie). Fresh auth ≤10 минут. **Scope:** не требуется. **Path** (обязателен каждый параметр): | Поле | Тип | Обязательно | Ограничения | | ---- | -------- | ----------- | --------------------------------------- | | `id` | `string` | да | формат "uuid"; pattern см. полную схему | **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 204, без тела. **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `403 CREDENTIAL_NOT_ALLOWED`, `401 REAUTH_REQUIRED`, `404 NOT_FOUND`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i -X DELETE https://aos.edgelab.space/api/v1/keys/00000000-0000-4000-8000-000000000001 \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \ -H 'Origin: https://aos.edgelab.space' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 204 | – | – | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, CREDENTIAL_NOT_ALLOWED, REAUTH_REQUIRED, NOT_FOUND | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `keysRevoke`. --- # GET /api/v1/keys/calls Последние вызовы REST/MCP: до 20 на ключ и до 100 суммарно, новые первыми. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/keys/calls` | | Доступ | Cookie кабинета | | Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) | | operationId | `keysCalls` | ## Описание Последние вызовы REST/MCP: до 20 на ключ и до 100 суммарно, новые первыми; данные хранятся 30 дней. `keyId` ограничивает выбор одним собственным ключом. Аргументы вызовов не сохраняются. **Auth:** сессия кабинета (cookie). **Scope:** не требуется. **Path:** параметров нет. **Query:** | Поле | Тип | Обязательно | Ограничения | | ------- | -------- | ----------- | --------------------------------------- | | `keyId` | `string` | нет | формат "uuid"; pattern см. полную схему | **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [ApiCallList](/docs/schemas#apicalllist). Краткая форма: `{ calls: (ApiCall)[] }`. Пример JSON; значения демонстрационные. ```json { "calls": [ { "id": "6c9d4f5b-2e70-4ba2-9d4e-5f6a7b8c9d0e", "keyId": "3f6a1c2e-9b4d-4e7f-8a1b-2c3d4e5f6a7b", "surface": "rest", "name": "GET /api/v1/lessons/{id}", "target": "1.1", "status": "200", "latencyMs": 42, "client": "claude-code/2.1.0", "at": "2026-11-10T09:35:00Z" }, { "id": "7d0e5a6c-3f81-4cb3-8e5f-6a7b8c9d0e1f", "keyId": "3f6a1c2e-9b4d-4e7f-8a1b-2c3d4e5f6a7b", "surface": "rest", "name": "GET /api/v1/search", "target": null, "status": "200", "latencyMs": 118, "client": "claude-code/2.1.0", "at": "2026-11-10T09:34:10Z" } ] } ``` **Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 CREDENTIAL_NOT_ALLOWED`, `422 VALIDATION_FAILED`; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/api/v1/keys/calls \ --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [ApiCallList](/docs/schemas#apicalllist) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `keysCalls`. --- # Личный менторинг Персональный трек, встречи, решения, задания и чат с ментором. Тарифы «С куратором / Лично с Даши». | Метод | Путь | Доступ | 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`. --- # GET /api/v1/mentoring/track Текущая опубликованная версия личного трека. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/track` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringTrack` | ## Описание Текущая опубликованная версия личного трека. Необязательный `versionId` из истории версий открывает конкретную публикацию. Ответ `MentoringPersonalTrack`: `{ id, title, updatedAt, version }`; детали версии – `markdown`, `sections`, `stages`, `metrics`, `changes`. Нет трека или версии – 404. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS https://aos.edgelab.space/api/v1/mentoring/track \ -H "Authorization: Bearer $AOS_API_KEY" ``` ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `versionId` | query | нет | `string` | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringPersonalTrack](/docs/schemas#mentoringpersonaltrack) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringTrack`. --- # GET /api/v1/mentoring/track/versions История опубликованных версий личного трека, включая прошлые публикации; черновики скрыты. id элемента – это versionId для чтения версии. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/track/versions` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringVersions` | ## Описание История опубликованных версий личного трека, включая прошлые публикации; черновики скрыты. `id` элемента – это `versionId` для чтения версии. Параметры `limit?`, `cursor?`. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringVersions](/docs/schemas#mentoringversions) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringVersions`. --- # GET /api/v1/mentoring/sessions Встречи с ментором. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/sessions` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringSessions` | ## Описание Встречи с ментором. Параметры `limit?`, `cursor?`. Детали элемента: `startsAt`, `kind` (`call` или `consultation`), `durationSeconds` (или null), `status`, `summary`, `transcriptStatus` и nullable `trackVersionId`. Если есть, приходят также `title` (название встречи, 1–120 символов), `brief` (короткое описание, 1–400 символов), `hostName` (имя ведущего, 1–64 символа) и `recordingUrl` (ссылка на запись, HTTPS, только `kinescope.io`); если их нет, поля отсутствуют. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ```bash curl -sS "https://aos.edgelab.space/api/v1/mentoring/sessions?limit=20" \ -H "Authorization: Bearer $AOS_API_KEY" ``` ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringSessions](/docs/schemas#mentoringsessions) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringSessions`. --- # GET /api/v1/mentoring/sessions/{sessionId} Одна встреча: краткое содержание или очищенный транскрипт. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/sessions/{sessionId}` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringSession` | ## Описание Одна встреча: краткое содержание или очищенный транскрипт. Параметры `view?` (`summary` по умолчанию или `transcript`), `limit?`, `cursor?` (только для транскрипта). ```json { "view": "summary", "session": { "id": "…", "updatedAt": "…", "refs": [], "details": { "startsAt": "…", "kind": "call", "durationSeconds": null, "status": "completed", "summary": "…", "transcriptStatus": "ready" }, "trackVersionId": null } } ``` С `view=transcript` ответ содержит метаданные встречи без summary, `transcriptStatus`, `items`, `nextCursor`, `updatedAt`. Сегмент: `ordinal`, `startSeconds`, `endSeconds`, `speakerRole`, `text`, `status`, необязательный `quality` (`verified`, `uncertain`, `redacted`); порядок – по `ordinal`. Отдаются только готовые сегменты. Состояния транскрипта: `not_provided`, `consent_required`, `processing`, `ready`, `failed`, `redacted`; при недоступном – пустая страница и явное состояние. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `sessionId` | path | да | `string` | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–200 | | `view` | query | нет | `summary` \| `transcript` | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringSessionRead](/docs/schemas#mentoringsessionread) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringSession`. --- # GET /api/v1/mentoring/decisions Решения со встреч. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/decisions` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringDecisions` | ## Описание Решения со встреч. Параметры `limit?`, `cursor?`, `sessionId?`, `status?` (`proposed`, `unconfirmed`, `confirmed`, `superseded`, `cancelled`). Детали: `text`, `authorRole`, `status`, nullable `dueAt`; nullable `sessionId`, `supersedesId`. Чужой или недоступный `sessionId` – 404. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | | `sessionId` | query | нет | `string` | | `status` | query | нет | `proposed` \| `unconfirmed` \| `confirmed` \| `superseded` \| `cancelled` | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringDecisions](/docs/schemas#mentoringdecisions) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringDecisions`. --- # GET /api/v1/mentoring/chat/digests Ежедневные сводки чата с ментором. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/chat/digests` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringDigests` | ## Описание Ежедневные сводки чата с ментором. Параметры `limit?`, `cursor?`, `from?`, `to?`. Детали: `date`, `timezone`, `summary`, `coverage`; `coverage` содержит `from`, `to` и `gaps[]` – пропуски с датами и причиной (`before_collection`, `stopped`, `unavailable_voice`, `sync_error`, `redacted`). Отсутствующая история никогда не додумывается. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | | `from` | query | нет | `string`, date | | `to` | query | нет | `string`, date | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringDigests](/docs/schemas#mentoringdigests) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringDigests`. --- # GET /api/v1/mentoring/chat/messages Очищенные разрешённые сообщения чата. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/chat/messages` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringMessages` | ## Описание Очищенные разрешённые сообщения чата. Параметры `limit?`, `cursor?`, `from?`, `to?`. Детали: `at`, `speakerRole` (`student`, `mentor`), `text`, `revision`. Сначала читайте сводки, чтобы понимать покрытие. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | | `from` | query | нет | `string`, date | | `to` | query | нет | `string`, date | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringMessages](/docs/schemas#mentoringmessages) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringMessages`. --- # GET /api/v1/mentoring/homework Задания от ментора. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/api/v1/mentoring/homework` | | Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth | | Scope для ключей | `mentoring:read` | | operationId | `mentoringHomework` | ## Описание Задания от ментора. Параметры `limit?`, `cursor?`, `sessionId?`, `status?` (`open`, `in_progress`, `done`, `cancelled`). Детали: `text`, `assigneeRole`, необязательное `assigneeName` (имя ответственного, если задание не ваше; нет поля или null – задание ваше), nullable `dueAt`, `doneCriteria`, `status`, nullable `stage`; nullable `sessionId`, `decisionId` и `dependencies` (UUID видимых заданий). Эндпоинт только читает: статус выполнения не меняется. **Лимиты:** API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. ## Параметры | Имя | Где | Обязательно | Тип и ограничения | | --- | --- | --- | --- | | `cursor` | query | нет | `string`, длина ≤ 2048 | | `limit` | query | нет | `integer`, 1–100 | | `sessionId` | query | нет | `string` | | `status` | query | нет | `open` \| `in_progress` \| `done` \| `cancelled` | ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [MentoringStudentHomework](/docs/schemas#mentoringstudenthomework) | Успех | | ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, CREDENTIAL_NOT_ALLOWED, INSUFFICIENT_SCOPE, MENTORING_NOT_AVAILABLE, NOT_FOUND, VALIDATION_FAILED | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `mentoringHomework`. --- # Служебные Проверка работоспособности. | Метод | Путь | Доступ | Scope | Назначение | | --- | --- | --- | --- | --- | | `GET` | [`/healthz`](/docs/api/ops/healthz) | Без авторизации | – | Проверка работоспособности и SHA установленной версии | --- # GET /healthz Проверка работоспособности и SHA установленной версии. | Поле | Значение | | --- | --- | | URL | `GET https://aos.edgelab.space/healthz` | | Доступ | Без авторизации | | Scope для ключей | не требуется | | operationId | `healthz` | ## Описание Проверка работоспособности и SHA установленной версии. **Auth:** без авторизации. **Scope:** не требуется. **Path:** параметров нет. **Query:** нет объявленных полей. **Body:** не требуется. **Ответ · статус и структура** **Ответ:** 200 `application/json`, [Health](/docs/schemas#health). Краткая форма: `{ status: "ok", sha: string }`. Пример JSON; значения демонстрационные. ```json { "status": "ok", "sha": "26a5908fc150956af910ab89cc5e6f8ece522a40" } ``` **Ошибки:** доменными ошибками контракт не дополнен; [общие ошибки](/docs/errors). **Лимиты:** Отдельного throttle в коде нет. ```bash curl -sS -i https://aos.edgelab.space/healthz ``` ## Ответы по контракту | Статус | Тип | Схема | Описание | | --- | --- | --- | --- | | 200 | application/json | [Health](/docs/schemas#health) | Успех | Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `healthz`. --- # MCP-сервер AgentOS Адрес – `https://aos.edgelab.space/mcp`, транспорт – **Streamable HTTP** без сессий: каждый запрос – один JSON-RPC 2.0 объект, ответ – JSON. Авторизация – OAuth access token или персональный API-ключ в `Authorization: Bearer …`; cookie кабинета и токен Mini App не подходят. Отдельных MCP resources и prompts нет – только [инструменты](/docs/mcp/tools). | Параметр | Значение | | --- | --- | | URL | `https://aos.edgelab.space/mcp` | | Имя сервера | `agentos` (`serverInfo.title`: AgentOS) | | Транспорт | Streamable HTTP, только `POST` | | Авторизация | OAuth (authorization code + PKCE S256, DCR) или API-ключ `aos3.sk_…` | | Инструменты | [Список и права](/docs/mcp/tools) | Пошаговое подключение с готовыми командами – в [Быстром старте](/docs/quickstart#3-подключите-mcp). ## Подключение за 1 минуту > [!TIP] > Выберите клиент и раскройте инструкцию. Для Claude.ai и ChatGPT используется OAuth с DCR; для CLI доступны персональные API-ключи. **Claude.ai** Откройте Connectors → Add custom connector (в новых версиях интерфейса Customize → Connectors), задайте имя `AgentOS` и URL `https://aos.edgelab.space/mcp`. Выберите OAuth-вход и автоматическую регистрацию клиента (**Register automatically / DCR**): AgentOS не поддерживает published identity / CIMD. Нажмите Connect, войдите по коду из почты в открывшейся вкладке (или выберите другой способ входа) и разрешите запрошенные права. После возврата включите connector в нужном чате. В организационном аккаунте добавление может требовать настроек владельца. [Инструкция Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). Claude обнаруживает AS через metadata, регистрируется, использует PKCE S256 и resource `/mcp`, затем предъявляет access token. Пользовательский API-ключ для этого сценария не нужен. Общее описание процесса и допустимые callback URLs: [OAuth](/docs/oauth). **ChatGPT** В интерфейсе, где доступно добавление собственного MCP server, выберите Add custom MCP server (например, Plugins → `+`), задайте URL `https://aos.edgelab.space/mcp`, OAuth и **DCR**. Пройдите вход и согласие AgentOS, затем включите полученное подключение. Имена пунктов зависят от версии и настроек workspace; наличие этой возможности в конкретном аккаунте код AgentOS не определяет. [Официальная инструкция OpenAI](https://developers.openai.com/plugins/build/app-quickstart). Сервер AgentOS допускает оба вида callback ChatGPT из своего allowlist и возвращает `iss` на authorize callback. Выбирайте регистрацию public client с `token_endpoint_auth_method=none`; `client_secret` не задаётся. [OAuth-требования OpenAI](https://developers.openai.com/plugins/build/auth). Эти шаги описывают предусмотренную кодом интеграцию. Локальные тесты проверяют протокол с SDK и fake-клиентами; успешное подключение конкретного аккаунта Claude.ai/ChatGPT на production ими не подтверждается. **Claude Code: API-ключ в заголовке** В кабинете откройте страницу API-ключей, создайте ключ с `course:read`; для анкеты и плана добавьте `profile:read`; для истории тьютора отдельно включите `tutor:read`; для отметок уроков и шагов плана – `progress:write`. Секрет показывается один раз. Пример команды: ```bash claude mcp add --scope user --transport http agentos https://aos.edgelab.space/mcp \ --header 'Authorization: Bearer aos_live_...' ``` Откройте `/mcp` в Claude Code и проверьте подключение. `aos_live_...` здесь и далее – **маска**, её нужно заменить выданным ключом. Настоящий формат ключа – `aos3.sk_` и 43 base64url-символа. CLI сохраняет конфигурацию подключения; обращайтесь с ней как с секретом. [Синтаксис Claude Code](https://code.claude.com/docs/en/mcp). **Codex** Для персонального ключа добавьте в свой `config.toml` (пользовательская конфигурация Codex или доверенная конфигурация проекта): ```toml [mcp_servers.agentos] url = "https://aos.edgelab.space/mcp" bearer_token_env_var = "AOS_API_KEY" ``` Перед запуском Codex задайте `AOS_API_KEY` выданным ключом в окружении своего терминала; в примерах это `aos_live_...`. Проверка списка: `codex mcp list`, в TUI – `/mcp`. Принцип настройки и поддержка Streamable HTTP подтверждены [официальной документацией OpenAI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). Вариант с OAuth: ```bash codex mcp add agentos --url https://aos.edgelab.space/mcp codex mcp login agentos ``` Используйте его вместо bearer-конфигурации того же подключения. Если клиент предлагает выбор регистрации, выбирайте DCR; в версиях с соответствующим флагом: `codex mcp login agentos --oauth-client-registration dcr`. Callback должен быть разрешённым локальным HTTP URL; remote HTTPS callback AgentOS allowlist не принимает. [OAuth и регистрация в Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ## Как проходит подключение ```mermaid sequenceDiagram actor Student as Студент participant Client as MCP-клиент participant AS as AgentOS OAuth participant MCP as AgentOS MCP Client->>MCP: POST /mcp без токена MCP-->>Client: 401 + resource_metadata Client->>AS: Discovery и DCR Client->>AS: Authorize + PKCE S256 + resource AS->>Student: Email-код или другой вход, затем согласие Student->>AS: Разрешить доступ AS-->>Client: code + state + iss Client->>AS: Обмен code + code_verifier AS-->>Client: Access token; refresh при зарегистрированном refresh grant Client->>MCP: Initialize, tools/list, tools/call с bearer MCP-->>Client: Результат в рамках прав студента ``` Без сессии OAuth показывает вход по 6-значному email-коду (10 минут, 5 попыток); pending flow хранится 30 минут. Consent показывает срок подключения: до 30 дней после использования при refresh grant, один час без него. Refresh доступен только зарегистрировавшим этот grant клиентам; сужение access scopes не сужает scopes refresh token. Metadata MCP включает `offline_access`. HTTP loopback callbacks допускают `localhost`, `127.0.0.1` и `[::1]` с любым допустимым портом и буквальным совпадением path/query; `[::1]` завершается через HTML-страницу с meta refresh и ссылкой. Подробности регистрации, email-лимитов, callback и rotation – в [OAuth](/docs/oauth). ## HTTP и формат ответа ### ALL /mcp Фактически смонтирован ALL-обработчик: `POST` обслуживает MCP, любой другой HTTP-метод получает `405 METHOD_NOT_ALLOWED` с `Allow: POST`. Проверка Origin выполняется до проверки метода. Поведение `POST`, `GET` и `DELETE` описано ниже. ### POST /mcp Каждый запрос требует `Authorization: Bearer aos_live_...` (API-ключ или OAuth access token); cookie кабинета и TMA не подходят. Для `initialize`, `tools/list`, `ping` отдельный scope не нужен, но проверяются token, участие и лимиты. Для `tools/call` scope зависит от инструмента. Path/query-параметров нет; тело – один JSON-RPC 2.0 объект, до **64 KiB**. Batch не поддерживается. Обязательные HTTP headers клиента: `Content-Type: application/json`, `Accept: application/json, text/event-stream`. После initialize отправляйте согласованную версию в `MCP-Protocol-Version`. Необязательный `Origin`, если передан, должен быть точно `https://aos.edgelab.space`. На каждый HTTP-запрос создаётся новый server: `Mcp-Session-Id` нет, SSE-подписок нет. Для новых версий SDK использует JSON; для старых клиентов может вернуть один конечный результат через SSE. ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0"}}}' curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` `initialize` возвращает результат MCP handshake: согласованную версию, server capabilities и `serverInfo` (`name: agentos`, `title: AgentOS`, `version: 1.0.0`, icons). `tools/list` возвращает `result.tools[]` с именем, описанием, `inputSchema`, `outputSchema`, annotations. `tools/call`: ```json { "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "{\"completed\":[],\"positions\":{},\"homework\":{},\"milestonesDone\":[]}" } ], "structuredContent": { "completed": [], "positions": {}, "homework": {}, "milestonesDone": [] } } } ``` `structuredContent` – тот же JSON, что соответствующий REST-метод, за исключением ограниченного `aos_whoami`. Ошибка внутри инструмента: `result.isError=true`, `content[0].text` содержит JSON REST envelope `{error:{code,message,retryAfterSec?,issues?}}`; это может прийти с HTTP 200. Недостаточный scope возвращается здесь же: `result.isError=true`, `error.code=INSUFFICIENT_SCOPE` в JSON из `content[0].text`, обычно с HTTP 200. Некорректные аргументы может отклонить SDK до вызова capability. HTTP-ошибки: `401 UNAUTHENTICATED` с discovery challenge; `403 CREDENTIAL_NOT_ALLOWED`, `ORIGIN_REJECTED`, `NO_ENTITLEMENT` (до инструмента); `429 RATE_LIMITED`; `503 ENTITLEMENT_UNAVAILABLE`; `500 INTERNAL`. MCP body cap – HTTP `413`, JSON-RPC `-32000`; invalid JSON – HTTP `400`, `-32700`; batch – HTTP `400`, `-32600`; `subscriptions/listen` – HTTP `200`, `-32601`. SDK также может отказать с `400`, `406`, `415` при нарушении протокола/headers. Подробности: [ошибки](/docs/errors). Лимиты общие с REST для конкретного ключа: **60/min**, **2000/UTC day**; на студента **3000/UTC day**; `aos_search` и `aos_get_transcript` дополнительно **20/min/key**. Вызов существующего инструмента сверх лимита после распознавания ключа получает `isError` с `RATE_LIMITED` и `retryAfterSec`; остальные запросы получают HTTP 429. Ответы персональные: `Cache-Control: private, no-store`, `Vary: Authorization`. ### GET /mcp Поток GET не поддерживается: HTTP **405** REST envelope с `METHOD_NOT_ALLOWED`, `Allow: POST`. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. При чужом Origin проверка выполняется раньше и даёт 403. Пример: ```bash curl -i https://aos.edgelab.space/mcp ``` ### DELETE /mcp Сессии MCP отсутствуют, удалять нечего: HTTP **405** REST envelope с `METHOD_NOT_ALLOWED`, `Allow: POST`. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. Чужой Origin даёт 403 раньше проверки метода. Другие методы также отклоняются. Пример: ```bash curl -i -X DELETE https://aos.edgelab.space/mcp ``` --- # Инструменты MCP 22 инструментов сервера `https://aos.edgelab.space/mcp`. Каждый требует свой scope у API-ключа или OAuth-доступа; инструменты менторинга – ещё и тариф «С куратором / Лично с Даши». Аргументы и ответы совпадают с соответствующими REST-методами. | Инструмент | Scope | Тариф | Действие | Назначение | | --- | --- | --- | --- | --- | | [`aos_whoami`](/docs/mcp/tools#aos_whoami) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Имя студента, тариф, с кем сопровождение (куратор или Даши), купленное предложение, статус анкеты и плана, а также права этого ключа и до какого числа он действует. | | [`aos_list_lessons`](/docs/mcp/tools#aos_list_lessons) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Уроки и эфиры курса с разделами, длительностью и отметкой, открыт ли урок. | | [`aos_get_lesson`](/docs/mcp/tools#aos_get_lesson) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Урок или эфир по коду (например «1.1»): видео, конспект, таймкоды, промпты, ссылки и домашнее задание. | | [`aos_get_transcript`](/docs/mcp/tools#aos_get_transcript) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Полный текст урока или эфира по коду, по фрагментам с началом в секундах от старта видео. | | [`aos_search`](/docs/mcp/tools#aos_search) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Ищет по транскриптам и таймкодам уроков/эфиров (без конспектов); каждый ответ указывает, где это было сказано, например «Урок 1.1 · 05:10». | | [`aos_next`](/docs/mcp/tools#aos_next) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Какой урок студенту смотреть следующим и почему: продолжить начатый, взять следующий, сначала заполнить анкету или курс уже пройден. | | [`aos_list_efirs`](/docs/mcp/tools#aos_list_efirs) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Расписание живых эфиров курса: дата и время начала (startsAt, UTC; эфиры идут в 19:00 по Москве), длительность, прошёл ли эфир и код записи, когда она появилась. | | [`aos_get_live_session`](/docs/mcp/tools#aos_get_live_session) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Текущий эфир (за сутки до начала, во время и три часа после) или ближайший следующий: фаза (upcoming, soon, live, ended), время начала, полный урок эфира с планом, теорией, ссылками и презентацией, а… | | [`aos_mark_lesson`](/docs/mcp/tools#aos_mark_lesson) | `progress:write` | Группа, С куратором / Лично с Даши | запись | Отметить урок/эфир просмотренным. | | [`aos_update_plan_milestone`](/docs/mcp/tools#aos_update_plan_milestone) | `progress:write` | Группа, С куратором / Лично с Даши | запись | Установить статус одного шага опубликованного персонального плана. | | [`aos_get_tutor_history`](/docs/mcp/tools#aos_get_tutor_history) | `tutor:read` | Группа, С куратором / Лично с Даши | чтение | Только собственный единый диалог с тьютором. | | [`aos_get_progress`](/docs/mcp/tools#aos_get_progress) | `course:read` | Группа, С куратором / Лично с Даши | чтение | Пройденные уроки, где студент остановился в каждом видео, домашние задания и отмеченные шаги плана. | | [`aos_get_my_plan`](/docs/mcp/tools#aos_get_my_plan) | `profile:read` | Группа, С куратором / Лично с Даши | чтение | Персональный план студента: письмо, стек, репозитории, скиллы, проект и шаги, когда план готов. | | [`aos_get_onboarding`](/docs/mcp/tools#aos_get_onboarding) | `profile:read` | Группа, С куратором / Лично с Даши | чтение | Ответы студента в анкете курса, выбранный сетап и статус анкеты. | | [`aos_get_personal_track`](/docs/mcp/tools#aos_get_personal_track) | `mentoring:read` | С куратором / Лично с Даши | чтение | Опубликованный личный трек: разделы, этапы, метрики и изменения. | | [`aos_list_personal_track_versions`](/docs/mcp/tools#aos_list_personal_track_versions) | `mentoring:read` | С куратором / Лично с Даши | чтение | История опубликованных версий трека. | | [`aos_list_mentoring_sessions`](/docs/mcp/tools#aos_list_mentoring_sessions) | `mentoring:read` | С куратором / Лично с Даши | чтение | Встречи, их краткое содержание, доступность транскрипта, а также title, brief, hostName и recordingUrl, если есть. | | [`aos_get_session`](/docs/mcp/tools#aos_get_session) | `mentoring:read` | С куратором / Лично с Даши | чтение | Краткое содержание или очищенный транскрипт встречи с title, brief, hostName и recordingUrl, если есть. | | [`aos_get_decisions`](/docs/mcp/tools#aos_get_decisions) | `mentoring:read` | С куратором / Лично с Даши | чтение | Решения, их подтверждение, сроки и связь со встречами. | | [`aos_get_mentoring_chat_digest`](/docs/mcp/tools#aos_get_mentoring_chat_digest) | `mentoring:read` | С куратором / Лично с Даши | чтение | Ежедневные сводки чата с ментором и пропуски в покрытии. | | [`aos_list_mentoring_messages`](/docs/mcp/tools#aos_list_mentoring_messages) | `mentoring:read` | С куратором / Лично с Даши | чтение | Очищенные разрешённые сообщения – после чтения сводок. | | [`aos_get_homework`](/docs/mcp/tools#aos_get_homework) | `mentoring:read` | С куратором / Лично с Даши | чтение | Задания менторинга, критерии выполнения, зависимости и сроки. | Входные схемы ниже – JSON Schema из зарегистрированных capabilities. `required` задаёт обязательные поля; `additionalProperties: false` запрещает неизвестные. Полные схемы выходов: [schemas.md](/docs/schemas). Инструменты чтения помечены `readOnlyHint=true`, `destructiveHint=false`; `aos_mark_lesson` и `aos_update_plan_milestone` – `readOnlyHint=false`, `destructiveHint=true` (изменяют прогресс). Все инструменты имеют `idempotentHint=true`, `openWorldHint=false`. Отдельных MCP resources и prompts в этой реализации нет. ## Курс и прогресс ### aos_whoami Имя студента, тариф, с кем сопровождение (куратор или Даши), купленное предложение, статус анкеты и плана, а также права этого ключа и до какого числа он действует. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [AgentWhoami](/docs/schemas), тот же JSON в текстовом `content`; `mentoring` и `offer` – только если HTTP-запрос MCP несёт `X-Aos-Accept: enrollment-labels`. Краткая форма: `{ name: string, flow: "agentos3", tier: "group" | "personal", mentoring?: "curator" | "dashi" | null, offer?: "tutoring" | null, onboarding: { status: "draft" | "in_review" | "plan_ready", done: boolean }, planReady: boolean, authKind: "agentKey", keyScopes: ("course:read" | "profile:read" | "progress:write")[], keyExpiresAt: string }`. Не возвращает идентификаторы студента или Telegram; OAuth тоже представлен как `authKind: agentKey`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_whoami","arguments":{}}}' ``` ### aos_list_lessons Уроки и эфиры курса с разделами, длительностью и отметкой, открыт ли урок. Можно сузить по разделу (sectionId) или типу (kind). **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "kind": { "type": "string", "enum": ["lesson", "tech", "stream"] } }, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [LessonList](/docs/schemas#lessonlist), тот же JSON в текстовом `content`. Краткая форма: `{ lessons: (LessonCard)[] }`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{"kind":"lesson"}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_list_lessons","arguments":{"kind":"lesson"}}}' ``` ### aos_get_lesson Урок или эфир по коду (например «1.1»): видео, конспект, таймкоды, промпты, ссылки и домашнее задание. Закрытый урок откроется после анкеты в кабинете. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": { "code": { "type": "string" } }, "required": ["code"], "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [LessonDetail](/docs/schemas#lessondetail), тот же JSON в текстовом `content`. Краткая форма: `{ id: LessonCode, week: integer, title: string, minutes: integer, tools: (string)[], summary: string, task: string, kind: LessonKind, sectionId: string, gated: boolean, locked: boolean, video: LessonVideo, konspekt: string, timecodes: (Timecode)[], prompts: (LessonPrompt)[], links: (LessonLink)[], plan: (LessonPlanStep)[], theory: (string)[], deck: LessonDeck | null }`. У эфира (`kind=stream`) те же поля урока плюс `plan`, `theory`, `deck`; у урока без них – пустые списки и `null`. `code` принимает строку; неверный/неизвестный код → `NOT_FOUND`, закрытый gated-урок → `ONBOARDING_REQUIRED`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`, `NOT_FOUND`, `ONBOARDING_REQUIRED`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{"code":"1.1"}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_lesson","arguments":{"code":"1.1"}}}' ``` ### aos_get_transcript Полный текст урока или эфира по коду, по фрагментам с началом в секундах от старта видео. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": { "code": { "type": "string" } }, "required": ["code"], "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [Transcript](/docs/schemas#transcript), тот же JSON в текстовом `content`. Краткая форма: `{ lessonId: LessonCode, segments: (object)[] }`. `code` принимает строку; неверный/неизвестный код → `NOT_FOUND`, закрытый gated-урок → `ONBOARDING_REQUIRED`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`, `NOT_FOUND`, `ONBOARDING_REQUIRED`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key. **Пример:** `{"code":"1.1"}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_transcript","arguments":{"code":"1.1"}}}' ``` ### aos_search Ищет по транскриптам и таймкодам уроков/эфиров (без конспектов); каждый ответ указывает, где это было сказано, например «Урок 1.1 · 05:10». **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": ["query"], "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [SearchResults](/docs/schemas#searchresults), тот же JSON в текстовом `content`. Краткая форма: `{ query: string, results: (object)[] }`. `query` – MCP-поле; адаптер преобразует его в REST `q`. `limit` default 10, 1–20. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key. **Пример:** `{"query":"MCP","limit":5}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_search","arguments":{"query":"MCP","limit":5}}}' ``` ### aos_next Какой урок студенту смотреть следующим и почему: продолжить начатый, взять следующий, сначала заполнить анкету или курс уже пройден. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [NextLesson](/docs/schemas#nextlesson), тот же JSON в текстовом `content`. Краткая форма: `{ lesson: LessonCard | null, reason: "continue" | "next" | "onboarding" | "done" }`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_next","arguments":{}}}' ``` ### aos_list_efirs Расписание живых эфиров курса: дата и время начала (startsAt, UTC; эфиры идут в 19:00 по Москве), длительность, прошёл ли эфир и код записи, когда она появилась. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [EfirList](/docs/schemas#efirlist), тот же JSON в текстовом `content`. Краткая форма: `{ efirs: (Efir)[] }`. `startsAt` в UTC: `2026-11-04T16:00:00Z` = 4 ноября, 19:00 МСК. `upcoming=false` и `lessonId` – эфир прошёл, запись открывается как урок с этим кодом. Файлы календаря: `https://aos.edgelab.space/calendar/agentos3-efirs.ics` (всё расписание) и `https://aos.edgelab.space/calendar/agentos3-<код>.ics` (один эфир), без авторизации. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_list_efirs","arguments":{}}}' ``` ### aos_get_live_session Текущий эфир (за сутки до начала, во время и три часа после) или ближайший следующий: фаза (upcoming, soon, live, ended), время начала, полный урок эфира с планом, теорией, ссылками и презентацией, адрес страницы эфира и презентации. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [LiveSession](/docs/schemas), тот же JSON в текстовом `content`. Краткая форма: `{ session: { phase, efir: Efir, lesson: LessonDetail, pageUrl, deckUrl } | null }`. Окно «Эфир сейчас»: `soon` – за 24 часа до `startsAt`, `live` – от начала до планового конца (`minutes`), `ended` – три часа после конца (запись ещё готовится); вне окна – ближайший следующий эфир с `phase=upcoming`, иначе `session: null`. `lesson` – эфир в форме урока, как у [`aos_get_lesson`](/docs/mcp/tools#aos_get_lesson): `plan` (шаги), `theory`, `links`, `deck`; запись (`video.url`) и транскрипт появляются после эфира. `pageUrl` и `deckUrl` – абсолютные адреса, например `https://aos.edgelab.space/#/lesson/stream.1` и `https://aos.edgelab.space/decks/agentos-demo-day-20261102.html`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_live_session","arguments":{}}}' ``` ### aos_mark_lesson Отметить урок/эфир просмотренным. **Scope:** `progress:write`. **Вход:** `{"code":"1.1","completed":true}`; оба поля обязательны, лишние запрещены. `code` – [LessonCode](/docs/schemas#lessoncode), `completed` – только literal `true`; `false` отклоняется. Позиция видео и домашнее задание сохраняются. Повтор не меняет отметку или дату завершения. **Выход:** [Progress](/docs/schemas#progress), общий с `PUT /api/v1/progress`. REST принимает `completed: false` как сохранение существующей отметки; отсутствие поля также сохраняет её. Завершение монотонно. **Ошибки:** `INSUFFICIENT_SCOPE` с именем `progress:write`, `VALIDATION_FAILED`, `NOT_FOUND`, `ONBOARDING_REQUIRED`, общие auth/entitlement ошибки и `INTERNAL`. **Лимиты и аудит:** общие с REST: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. В аудите есть код урока, но нет аргументов. ### aos_update_plan_milestone Установить статус одного шага опубликованного персонального плана. **Scope:** `progress:write`. **Вход:** `{"milestone":0,"completed":true,"expectedVersion":1}`; все три поля обязательны, лишние запрещены. `milestone` – целое 0–11, индекс шага от нуля; он должен существовать в текущем плане. `completed` – boolean: true отмечает, false снимает отметку. Остальные шаги сохраняются. `expectedVersion` – положительная версия из `aos_get_my_plan`. Проверяется под lock публикации до записи: новая версия между чтением и повтором → `VERSION_CONFLICT`, новый план и его отметки не меняются. Повтор идемпотентен; параллельные отметки не теряются. **Выход:** [Progress](/docs/schemas#progress). Общий обработчик с `PUT /api/v1/plan/milestones`, который принимает `{milestonesDone, expectedVersion}` и заменяет весь набор отметок. Отметки принадлежат версии опубликованного плана; новая версия начинает с пустого набора. **Ошибки:** `INSUFFICIENT_SCOPE` с именем `progress:write`, `VALIDATION_FAILED` для отсутствующего индекса, `NOT_FOUND` без опубликованного плана, `VERSION_CONFLICT` при смене версии, общие auth/entitlement ошибки и `INTERNAL`. ### aos_get_tutor_history Только собственный единый диалог с тьютором. **Scope:** `tutor:read`, отдельное opt-in разрешение на историю чата. Не входит в default scopes; существующие `profile:read` ключи/grants не открывают историю, refresh не повышает права. OAuth consent и кабинет показывают отдельное разрешение; `scopes_supported` и DCR принимают `tutor:read`. Отправка сообщений, факты тьютора и скачивание файлов остаются доступны только кабинету/TMA. **Вход:** `{"limit":20,"cursor":""}`; оба поля необязательны, лишние запрещены. `limit` – целое 1–50, default 20. `cursor` – `nextCursor` предыдущего ответа; выбирает более старые сообщения. Неизвестный или чужой cursor возвращает пустую страницу без раскрытия владельца. **Выход:** `{messages: [...], nextCursor: UUID | null}`. Сообщения отсортированы по `(created_at, id)` по убыванию. Каждое содержит `id`, `role` (user/assistant), `text`, `created_at` (ISO-8601), `sources`, `citations`, `error`, `feedback`, `attachments`. Источники и цитаты используют [TutorMessage](/docs/schemas#tutormessage); старые ответы без цитат возвращают пустой список. Вложения – только `{id,name,mime,size}`, без URL, байтов и извлечённого текста. История доступна и при выключенной генерации тьютора, без вызова модели. **Ошибки:** `INSUFFICIENT_SCOPE` с именем `tutor:read`, `VALIDATION_FAILED`, общие auth/entitlement ошибки, `INTERNAL`. **Лимиты:** общие с REST: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. Аудит не содержит текста, cursor или вложений. ### aos_get_progress Пройденные уроки, где студент остановился в каждом видео, домашние задания и отмеченные шаги плана. **Auth:** API-ключ / OAuth token. **Scope:** `course:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [Progress](/docs/schemas#progress), тот же JSON в текстовом `content`. Краткая форма: `{ completed: (LessonCode)[], positions: Record, homework: Record, milestonesDone: (integer)[] }`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_progress","arguments":{}}}' ``` ### aos_get_my_plan Персональный план студента: письмо, стек, репозитории, скиллы, проект и шаги, когда план готов. **Auth:** API-ключ / OAuth token. **Scope:** `profile:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [PlanResponse](/docs/schemas#planresponse), тот же JSON в текстовом `content`. Краткая форма: `{ status: OnboardingStatus, plan: PlanContent | null, version: integer | null, publishedAt: string | null }`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_my_plan","arguments":{}}}' ``` ### aos_get_onboarding Ответы студента в анкете курса, выбранный сетап и статус анкеты. **Auth:** API-ключ / OAuth token. **Scope:** `profile:read`. **Параметры · JSON Schema** ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Выход:** `result.structuredContent` – [Onboarding](/docs/schemas#onboarding), тот же JSON в текстовом `content`. Краткая форма: `{ schemaVersion: 2, status: OnboardingStatus, step: integer, answers: OnboardingDraft, completedAt: string | null }`. **Ошибки:** общие auth/entitlement/лимиты выше, внутри tool – `INSUFFICIENT_SCOPE`, `VALIDATION_FAILED`, `INTERNAL`. **Лимиты:** общие 60/min/key, 2000/UTC day/key, 3000/UTC day/student. **Пример:** `{}`. После initialize: ```bash curl -sS https://aos.edgelab.space/mcp \ -H 'Authorization: Bearer aos_live_...' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-03-26' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aos_get_onboarding","arguments":{}}}' ``` ## Личный менторинг ### aos_get_personal_track Опубликованный личный трек: разделы, этапы, метрики и изменения. Необязательный `versionId`; ответ как у `GET /api/v1/mentoring/track`. **Scope:** `mentoring:read`. ### aos_list_personal_track_versions История опубликованных версий трека. Аргументы `limit?`, `cursor?`; ответ как у `/track/versions`. **Scope:** `mentoring:read`. ### aos_list_mentoring_sessions Встречи, их краткое содержание, доступность транскрипта, а также `title`, `brief`, `hostName` и `recordingUrl`, если есть. Аргументы `limit?`, `cursor?`; ответ как у `/sessions`. **Scope:** `mentoring:read`. ### aos_get_session Краткое содержание или очищенный транскрипт встречи с `title`, `brief`, `hostName` и `recordingUrl`, если есть. Обязательный `sessionId`, необязательные `view`, `limit`, `cursor`; ответ как у `/sessions/{sessionId}`. По умолчанию – краткое содержание; страницы транскрипта содержат секунды и явные состояния доступности. **Scope:** `mentoring:read`. ### aos_get_decisions Решения, их подтверждение, сроки и связь со встречами. Аргументы `limit?`, `cursor?`, `sessionId?`, `status?`; ответ как у `/decisions`. **Scope:** `mentoring:read`. ### aos_get_mentoring_chat_digest Ежедневные сводки чата с ментором и пропуски в покрытии. Аргументы `limit?`, `cursor?`, `from?`, `to?`; ответ как у `/chat/digests`. **Scope:** `mentoring:read`. ### aos_list_mentoring_messages Очищенные разрешённые сообщения – после чтения сводок. Аргументы `limit?`, `cursor?`, `from?`, `to?`; ответ как у `/chat/messages`. **Scope:** `mentoring:read`. ### aos_get_homework Задания менторинга, критерии выполнения, зависимости и сроки. Аргументы `limit?`, `cursor?`, `sessionId?`, `status?`; ответ как у `/homework`. **Scope:** `mentoring:read`. --- # OAuth для MCP MCP-клиенты (Claude.ai, ChatGPT, Codex и собственные агенты) получают доступ к `https://aos.edgelab.space/mcp` по OAuth 2.1 без client secret: public client, authorization code с PKCE **S256**, refresh rotation. Issuer – `https://aos.edgelab.space`, единственный поддержанный resource – **`https://aos.edgelab.space/mcp`** (без завершающего `/`). Client secret, Basic auth, implicit и client credentials не поддерживаются. Access token – непрозрачный bearer `aos3.sk_…`, не JWT. Права, срок и отзыв проверяются сервером; лимиты и scopes те же, что у [API-ключа](/docs/auth). ## Поток авторизации ```mermaid sequenceDiagram actor Student as Студент participant Client as MCP-клиент participant AS as AgentOS OAuth Client->>AS: POST /oauth/register (DCR) AS-->>Client: client_id, без client_secret Client->>AS: GET /oauth/authorize + PKCE S256 + resource AS->>Student: Вход и форма согласия Student->>AS: Разрешить AS-->>Client: Callback: code + state + iss Client->>AS: POST /oauth/token (code, code_verifier) AS-->>Client: Access token (1 час), refresh (30 суток) Client->>AS: POST /oauth/token (refresh_token) AS-->>Client: Новая пара токенов ``` 1. Клиент читает discovery и регистрируется через DCR. 2. Открывает в браузере `/oauth/authorize` с PKCE S256 и `resource`. 3. Студент входит (кабинет или код на email) и подтверждает доступ. 4. Клиент меняет `code` на токены и ходит в `https://aos.edgelab.space/mcp` с `Authorization: Bearer …`. > [!WARNING] > Refresh token одноразовый. Сериализуйте refresh и сохраняйте последнюю пару токенов атомарно: повтор уже использованного refresh token отзывает всё подключение. ## Discovery | Документ | Назначение | | --- | --- | | `GET /.well-known/oauth-authorization-server` | Метаданные сервера авторизации: endpoints, `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported: ["none"]`, scopes | | `GET /.well-known/oauth-protected-resource/mcp` | Метаданные ресурса MCP: `resource`, `authorization_servers`, scopes | Оба документа публичные, без авторизации. Неавторизованный `POST /mcp` возвращает `401` и `WWW-Authenticate: Bearer resource_metadata="https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp"`; при недействительном токене добавляется `error="invalid_token"`. ```bash curl -sS https://aos.edgelab.space/.well-known/oauth-authorization-server curl -sS https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp ``` ## Dynamic Client Registration `POST /oauth/register`, тело `application/json` до 16 KiB, авторизация не нужна. | Поле | Тип | Обязательно | Значение | | --- | --- | --- | --- | | `redirect_uris` | string[] | да | 1–10 URI из списка ниже | | `client_name` | string | нет | 1–100 символов; по умолчанию `MCP client` | | `token_endpoint_auth_method` | string | нет | Только `none` | | `grant_types` | string[] | нет | `authorization_code` и, по желанию, `refresh_token`; по умолчанию оба | | `response_types` | string[] | нет | `["code"]` | | `scope` | string | нет | Scopes через пробел; согласие студента всё равно обязательно | | `logo_uri` | string URL | нет | Только HTTPS | Ответ `201`: поля регистрации, `client_id` и `client_id_issued_at`. `client_secret` не выдаётся. Клиент без `refresh_token` в `grant_types` получает только access token. ```bash curl -sS https://aos.edgelab.space/oauth/register \ -H 'Content-Type: application/json' \ -d '{"client_name":"Example client","redirect_uris":["http://localhost:8765/callback"],"token_endpoint_auth_method":"none"}' ``` Разрешённые redirect URIs: - `https://claude.ai/api/mcp/auth_callback` и `https://claude.com/api/mcp/auth_callback`; - `https://chatgpt.com/connector_platform_oauth_redirect` и `https://chatgpt.com/connector/oauth/{callback_id}`; - локальные `http://localhost[:port]/...`, `http://127.0.0.1[:port]/...`, `http://[::1][:port]/...` – для них может меняться только порт. HTTPS-адрес должен совпасть с зарегистрированным посимвольно. При обмене code нужен **тот же `redirect_uri`, что был в authorize**, включая порт. ## Авторизация и согласие `GET /oauth/authorize` открывается в браузере студента. Без сессии кабинета показывается вход по коду из email (6 цифр, действует 10 минут) со ссылкой на другие способы входа; затем – форма согласия с именем клиента и запрошенными правами. | Параметр | Обязательно | Значение | | --- | --- | --- | | `client_id` | да | Из DCR | | `redirect_uri` | да | Один из зарегистрированных | | `response_type` | да | `code` | | `code_challenge` | да | `BASE64URL(SHA256(code_verifier))`, 43 символа | | `code_challenge_method` | да | `S256` | | `resource` | да | `https://aos.edgelab.space/mcp` | | `scope` | нет | Через пробел; по умолчанию `course:read profile:read` | | `state` | нет | До 2048 символов, возвращается без изменений | Нужен хотя бы один scope из `course:read`, `profile:read`, `progress:write`, `tutor:read`, `mentoring:read`; дополнительно можно `offline_access`. Пустой, неизвестный scope или один `offline_access` отклоняются. После решения студента браузер возвращается на callback: при согласии – `code` (действует **90 секунд**, одноразовый), при отказе – `error=access_denied`; в обоих случаях `state` и `iss`. Клиент обязан проверить `state` и `iss`. ```bash curl -i -G https://aos.edgelab.space/oauth/authorize \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'redirect_uri=http://localhost:8765/callback' \ --data-urlencode 'response_type=code' \ --data-urlencode 'resource=https://aos.edgelab.space/mcp' \ --data-urlencode 'code_challenge=PKCE_S256_CHALLENGE_43_CHARACTERS_PLACEHOLDER' \ --data-urlencode 'code_challenge_method=S256' \ --data-urlencode 'scope=course:read profile:read offline_access' \ --data-urlencode 'state=CLIENT_RANDOM_STATE' ``` ## Токены `POST /oauth/token`, тело `application/x-www-form-urlencoded` до 16 KiB. Клиент идентифицируется `client_id`; заголовок `Authorization` и поле `client_secret` дают `401 invalid_client`. | Поле | Когда | Значение | | --- | --- | --- | | `grant_type` | всегда | `authorization_code` или `refresh_token` | | `client_id` | всегда | Из DCR | | `code` | code | Код из callback | | `redirect_uri` | code | Точная строка из authorize | | `code_verifier` | code | 43–128 символов `[A-Za-z0-9._~-]` | | `resource` | code | `https://aos.edgelab.space/mcp`; при refresh можно опустить | | `refresh_token` | refresh | Последний выданный refresh token | | `scope` | нет | Подмножество изначально выданных scope; шире нельзя | ```json { "access_token": "aos3.sk_...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN_PLACEHOLDER", "scope": "course:read profile:read offline_access" } ``` Refresh token выдаётся клиентам с `refresh_token` в `grant_types`. Каждый refresh выдаёт новую пару и заново проверяет участие студента в курсе. `scope` в refresh сужает только новый access token; refresh token сохраняет изначально выданные права, и следующий refresh без `scope` (или с более широким подмножеством) может вернуть их. Шире изначально выданных scope права не становятся никогда: такой запрос получает `400 invalid_grant`, а refresh token остаётся действующим. Повтор использованного code или refresh тем же клиентом отзывает подключение со всеми токенами. ```bash curl -sS https://aos.edgelab.space/oauth/token \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'code=AUTHORIZATION_CODE_PLACEHOLDER' \ --data-urlencode 'redirect_uri=http://localhost:8765/callback' \ --data-urlencode 'code_verifier=CLIENT_PKCE_VERIFIER_PLACEHOLDER' \ --data-urlencode 'resource=https://aos.edgelab.space/mcp' curl -sS https://aos.edgelab.space/oauth/token \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'refresh_token=LATEST_REFRESH_TOKEN_PLACEHOLDER' ``` ## Отзыв и подключения - `POST /oauth/revoke` (form `application/x-www-form-urlencoded`: `client_id`, `token`) отзывает всё подключение, к которому относится токен клиента. Корректный запрос, прошедший проверки, получает `200` с пустым телом, даже если токен неизвестен или уже отозван. Неполная или повторяющая параметры форма даёт `400 invalid_request`, `client_secret` или заголовок `Authorization` – `401 invalid_client`. При `429 temporarily_unavailable` токен не отозван: повторите тот же запрос после `Retry-After`. - Студент видит и отключает свои подключения на странице `/oauth/connections` (вход в кабинет обязателен). - Если участие в курсе закончилось, все подключения и токены студента отзываются; после восстановления нужно подключиться заново. ## Сроки | Объект | Срок | | --- | --- | | Вход по email в рамках авторизации | 30 минут | | Authorization code | 90 секунд, один раз | | Access token | 1 час (3600 секунд) | | Refresh token | 30 суток с каждой выдачи, одноразовый | | Подключение с refresh | до 30 дней после последнего использования | ## Ошибки OAuth-ошибки приходят как JSON с полем `error` или как параметр `error` на callback. | Код | Когда | | --- | --- | | `invalid_request` | Неверная или неполная форма, PKCE challenge, повтор параметров | | `invalid_redirect_uri`, `invalid_client_metadata` | DCR: redirect URI не из списка или поля не прошли проверку | | `invalid_scope`, `invalid_target`, `unsupported_response_type` | Authorize: неверные scope, `resource` или `response_type` | | `access_denied` | Студент отказал | | `invalid_client`, `unauthorized_client`, `unsupported_grant_type` | Token: неизвестный клиент, незарегистрированный grant, неверный `grant_type` | | `invalid_grant` | Code или refresh истёк, использован, не совпали PKCE/redirect/scope, участие закончилось | | `temporarily_unavailable` | `429` или `503`: повторите после `Retry-After` (если заголовка нет – с экспоненциальной паузой) | | `server_error` | `500`, непредвиденная ошибка | Регистрация, обмен и отзыв токенов ограничены по частоте; при `429` или `503` ждите время из `Retry-After`. Полный справочник – [Ошибки](/docs/errors#oauth). ## Scope `mentoring:read` Discovery, DCR, согласие и выдача токенов поддерживают и `mentoring:read` – чтение [личного менторинга](/docs/api/mentoring). Он никогда не выдаётся по умолчанию, не добавляется к существующим ключам, подключениям и refresh-токенам, а refresh не расширяет grant. Нужен тариф «Лично». --- # Ошибки ## REST envelope ```json { "error": { "code": "VALIDATION_FAILED", "message": "Некорректный запрос", "issues": [{ "path": "text", "message": "Напишите вопрос" }] } } ``` | Поле | Тип | Обязательно | Правило | | --------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------------------- | | `error` | object | да | Контейнер ошибки | | `error.code` | string enum | да | Один из кодов таблицы ниже | | `error.message` | string | да | 1–500 символов, безопасный русский текст; конкретный сервис может заменить default | | `error.retryAfterSec` | positive integer | нет | Задержка в секундах; renderer также ставит `Retry-After` | | `error.issues` | `{path:string,message:string}[]` | нет | До 50 проблем, path через точку; сообщения Zod могут быть на английском | Статус определяется кодом, а не текстом. По `message` нельзя строить ветвление клиента. При наличии retry-поля доверяйте ему, а не фиксированной паузе. Если поля нет, это не обещание, что повтор сразу разрешён. Неверный JSON – 422, а неверный UUID в большинстве resource paths – 404. Internal oversized body – 422; OAuth/MCP используют отдельные 413 форматы. ## Все REST error codes Ниже **26** кодов. | Code | HTTP | Default message | Что означает / действие | | ------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `VALIDATION_FAILED` | 422 | Некорректный запрос | Исправить поля из issues. Также raw media/type/size, неверный JSON, пустой вопрос или недопустимые вложения. | | `ONBOARDING_INCOMPLETE` | 422 | Анкета заполнена не полностью | Заполнить обязательные ответы анкеты и выбранные варианты «Другое»; повторить submit. | | `UNAUTHENTICATED` | 401 | Нужно войти в кабинет | Войти заново либо заменить неизвестный, истёкший или отозванный token. Cookie не подменяет явно переданный bearer. | | `LOGIN_INVALID` | 401 | Не удалось войти через Telegram, попробуйте ещё раз | Повторить вход; для password login текст одинаков для неверной пары и неизвестного email. | | `LINK_INVALID` | 401 | Ссылка для входа недействительна или устарела. Запросите новую в боте | Запросить новую ссылку. Одноразовый токен уже использован, истёк или недействителен. | | `REAUTH_REQUIRED` | 401 | Для этого действия войдите заново | Пройти новый вход. Для управления ключами и revoke-all нужна web-аутентификация ≤10 минут; для первого setup почты – свежий Telegram-вход. | | `CREDENTIAL_NOT_ALLOWED` | 403 | Это действие доступно только в веб-кабинете | Использовать разрешённый тип credential. Например, ключ агента не может вызывать tutor, transcribe или keys management. | | `INSUFFICIENT_SCOPE` | 403 | Недостаточно прав | Создать ключ/повторно согласовать OAuth с нужным scope. Правильный scope не отменяет ограничение credential type. | | `ORIGIN_REJECTED` | 403 | Запрос отклонён | Передать точный Origin кабинета; при отсутствии Origin допустим Sec-Fetch-Site: same-origin. Для MCP отсутствие Origin разрешено. | | `LOGIN_STATE_INVALID` | 403 | Сессия входа устарела, начните вход заново | Начать Telegram OIDC вход заново: state cookie/запрос отсутствует, отличается или истёк. | | `NO_ENTITLEMENT` | 403 | Нет доступа к кабинету | Проверить участие в потоке/блокировку. Login и refresh не должны продолжаться при отрицательном решении. | | `MENTORING_NOT_AVAILABLE` | 403 | Personal mentoring is unavailable | Mentoring reads require personal mentoring on the enrollment (`Me.mentoring` is `curator` or `dashi`, whatever the tier), checked within 15 minutes; no outage grace. No student/source metadata is disclosed. | | `ONBOARDING_REQUIRED` | 403 | Урок откроется после анкеты | Пройти анкету в кабинете; повторить чтение gated-урока или сохранение его прогресса. | | `NOT_FOUND` | 404 | Не найдено | Проверить код/id и доступ. Чужой ресурс не раскрывается. OIDC/mail endpoints могут быть выключены; plan/milestones пока не зарегистрирован. | | `VERSION_CONFLICT` | 409 | Данные изменились, обновите и повторите | Перечитать актуальные данные, затем повторить с новым `expectedVersion`. Также возможен конфликт password setup или avatar unchanged. | | `BUSY` | 409 | Предыдущая запись ещё расшифровывается, подождите | Дождаться текущей операции студента. Используется для dictation и tutor; сообщение зависит от операции. | | `METHOD_NOT_ALLOWED` | 405 | Метод не поддерживается | Использовать документированный HTTP-метод. Для /mcp разрешён только POST. | | `RATE_LIMITED` | 429 | Слишком много запросов, попробуйте позже | Дождаться retryAfterSec / Retry-After; не запускать цикл мгновенных повторов. Для upload занятость сервера даёт этот код с retryAfterSec=60; серверный отказ возвращает дневную попытку, превышение 2 PDF-резерваций владельца – нет. | | `DAILY_LIMIT` | 429 | Дневной лимит диктовки исчерпан, попробуйте завтра | Дождаться 00:00 МСК. Это секунды диктовки, сообщения/USD тьютора или попытки загрузки файлов; message переопределяется сервисом. | | `GLOBAL_BUDGET` | 429 | Тьютор отдыхает до 03:00 МСК. Попробуйте после этого времени | Тьютор приостановлен для всех до 00:00 UTC (03:00 МСК). Дождаться retryAfterSec. | | `KEY_LIMIT` | 409 | Уже есть 3 активных ключа, отзовите один из них | Уже 3 активных персональных ключа; отозвать один перед созданием. OAuth access keys в эту квоту не входят. | | `KEY_RATE` | 429 | Сегодня создано слишком много ключей, попробуйте завтра | Достигнуты 10 созданий персональных ключей за день МСК (rotation тоже создание). Дождаться 00:00 МСК. | | `STORAGE_LIMIT` | 409 | Место для файлов закончилось: до 200 МБ за 30 дней. Удалите неотправленные файлы или подождите, пока старые перестанут учитываться | Все unattached + attached за последние 30 суток занимают 200 MiB. Удалить неприкреплённые файлы или дождаться выхода старых из окна. | | `ENTITLEMENT_UNAVAILABLE` | 503 | Не удалось проверить доступ, попробуйте через пару минут | Повторить после Retry-After, если он задан. Read может работать в grace по cached решению; tutor POST в grace не работает. | | `DICTATION_UNAVAILABLE` | 503 | Диктовка сейчас недоступна, напишите текстом | Диктовка не настроена или STT недоступен. Написать текстом либо повторить позже. | | `TUTOR_UNAVAILABLE` | 503 | Тьютор временно недоступен. Попробуйте чуть позже | Тьютор выключен, провайдер недоступен, превышены внутренние ограничения запуска или невозможно сформировать ответ. Проверить retryAfterSec. | | `INTERNAL` | 500 | Внутренняя ошибка | Непредвиденная ошибка; детали не возвращаются клиенту. Повторять запись только с её правилом идемпотентности. | ## OAuth OAuth subrouter использует собственный JSON envelope (строка `error`, без REST `message`); браузерные email-формы также возвращают HTML-ошибки, описанные ниже: ```json { "error": "invalid_grant" } ``` | Code | HTTP / способ доставки | Причина | | --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `invalid_request` | 400; authorize также 302 на проверенный callback; body cap 413 | Некорректная/повторяющаяся форма, missing fields, pending cookie/record, CSRF (включая disconnect), PKCE challenge, непроверенный client/redirect | | `invalid_redirect_uri` | 400 при DCR | redirect_uris не соответствует allowlist | | `invalid_client_metadata` | 400 при DCR | Другие поля регистрации не проходят схему; `grant_types` обязательно включает `authorization_code` | | `unsupported_response_type` | 302 authorize callback | response_type отличается от code | | `invalid_target` | 302 authorize callback / 400 token | resource не совпадает с точным MCP URL; обязателен для code flow | | `invalid_scope` | 302 authorize callback | Неизвестные scopes либо нет ни одного student scope | | `access_denied` | 302 callback / 403 JSON при Origin error | Пользователь отказал или Origin отклонён | | `login_required` | 401 либо исходный HTTP-статус ApiError | Нет подходящей web-сессии; ApiError внутри OAuth отображаются так (например, 403/503 участия), кроме HTML-ответов verify ниже | | `invalid_client` | 400 token; 401 form endpoints | На token неизвестен/отсутствует client_id → 400. На token/revoke/email/disconnect предъявлен Authorization или client_secret → 401 | | `unauthorized_client` | 400 token | Известный клиент не зарегистрировал запрошенный grant (например, refresh для code-only клиента) | | `unsupported_grant_type` | 400 token | grant_type не authorization_code/refresh_token | | `invalid_grant` | 400 token | Code/refresh истёк, использован, неверен; PKCE/redirect/client/scope не совпали; участие отозвано | | `temporarily_unavailable` | 429 с Retry-After; 503 DCR / refresh | OAuth throttle; DCR временно не принимает регистрации (503, Retry-After: 300); refresh entitlement outage (503 без Retry-After) | | `server_error` | 500 | Непредвиденная ошибка OAuth без раскрытия exception/token | | `invalid_token` | Параметр WWW-Authenticate при HTTP 401 /mcp | Предъявленный MCP token недействителен; отсутствует, если token не был предъявлен | На authorize ошибки отправляются на callback **только после проверки redirect**. Callback содержит `state` (если был) и `iss`; для `[::1]` результат POST consent доставляется через HTML completion page с meta refresh и ссылкой. До проверки redirect ошибка остаётся локальным JSON. Без сессии GET authorize показывает email-вход (200 HTML) и создаёт pending flow; GET connections перенаправляет на login. Неверный scope на token endpoint – `invalid_grant`: разрешено непустое подмножество consented scopes (code) или scopes предъявленного refresh, с хотя бы одним student scope. Порядок и повторы несущественны; повышение прав отклоняется. Сужение access при refresh не сужает новый refresh token. Replay code с правильными client/PKCE/redirect/resource либо использованного refresh отзывает весь grant и выданные tokens, возвращая `invalid_grant`. Email-формы: неверный/истёкший код и исчерпанные 5 попыток дают **400 HTML**, без JSON error code. Rate limit на `/oauth/email/*` при синтаксически корректной pending cookie – **429 HTML** + `Retry-After`. На verify ApiError, кроме Origin rejection, также дают нейтральную HTML-страницу с исходным статусом (например, 401/403/503), если такая cookie есть; в остальных случаях ApiError отображается как `login_required`. Discovery живёт вне OAuth subrouter и использует общий обработчик ошибок приложения. ## MCP До выполнения инструмента MCP может вернуть REST envelope с HTTP 401/403/429/503/500. Если известный tool превысил лимит после распознавания живого ключа, ответ – tool error с `RATE_LIMITED` и `retryAfterSec`, часто HTTP 200. Успех транспорта не означает успех инструмента: ```json { "jsonrpc": "2.0", "id": 3, "result": { "isError": true, "content": [ { "type": "text", "text": "{\"error\":{\"code\":\"INSUFFICIENT_SCOPE\",\"message\":\"Недостаточно прав\"}}" } ] } } ``` Ошибки HTTP-адаптера JSON-RPC: | JSON-RPC code | HTTP | Message / причина | | ------------- | ---- | -------------------------------------- | | `-32700` | 400 | Parse error: тело не является JSON | | `-32600` | 400 | Batch requests are not supported | | `-32601` | 200 | Method not found: subscriptions/listen | | `-32000` | 413 | Request body too large: более 64 KiB | Пример: `{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}`. Дополнительно SDK v2 валидирует MCP envelopes/arguments и headers (возможны HTTP 400/406/415 и protocol/tool errors). Этот справочник перечисляет коды, заданные собственным кодом AgentOS; полный набор внутренних диагностик стороннего SDK не является контрактом AgentOS. GET/DELETE и остальные методы /mcp – 405 `METHOD_NOT_ALLOWED`, `Allow: POST`; чужой Origin отклоняется раньше проверки метода. Внутренние ошибки tool не возвращают stack trace. Сообщение `ONBOARDING_REQUIRED` направляет студента в `/#/onboarding`, `INSUFFICIENT_SCOPE` – к созданию ключа с нужным правом. --- # Лимиты ## Главное для агента | Лимит | Значение | | --- | --- | | Запросов на ключ в минуту | 60 (REST и MCP вместе) | | Запросов на ключ в сутки | 2000 (сутки UTC) | | Запросов на студента в сутки | 3000 по всем ключам (сутки UTC) | | Поиск и транскрипты | дополнительно 20 в минуту на ключ | | Тело запроса MCP | до 64 KiB, один JSON-RPC объект | Окна фиксированные. При превышении – `429 RATE_LIMITED`, заголовок `Retry-After` и `error.retryAfterSec` в теле; в MCP вызов инструмента возвращает `isError: true` с тем же кодом. Подождите указанное время и повторите. ## Общие правила Формат REST: `{ "error": { "code": "VALIDATION_FAILED", "message": "Некорректный запрос", "issues": [{"path":"field","message":"..."}] } }`. [Все коды, HTTP статусы и retry](/docs/errors). Для любого обработчика возможен `500 INTERNAL`; неизвестный URL – `404 NOT_FOUND`, другой метод на зарегистрированном REST path – `405 METHOD_NOT_ALLOWED`. Для защищённых маршрутов дополнительно действуют проверки middleware: `401 UNAUTHENTICATED`, `403 CREDENTIAL_NOT_ALLOWED` при неподходящем типе credential; при scope – `403 INSUFFICIENT_SCOPE`. Неверные UUID, обрабатываемые `parseParams`, дают 404, а не 422. Если у маршрута «отдельного throttle нет», это не обещание неограниченного использования, а отсутствие отдельного счётчика в текущем коде. Agent-key/OAuth лимиты REST и MCP общие: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; transcript/search дополнительно 20/min/key. Окна фиксированные, при отказе `429 RATE_LIMITED`, `Retry-After` и `error.retryAfterSec`. Квоты создания ключей, файлов, диктовки и тьютора используют **день МСК**, пауза тьютора `GLOBAL_BUDGET` – **UTC**. Прокси может вернуть собственную ошибку без REST envelope (например, oversized body). ## Лимиты по эндпоинтам | Эндпоинт | Лимиты | | --- | --- | | [`POST /api/v1/auth/link/inspect`](/docs/api/auth/auth-link-inspect) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/link/redeem`](/docs/api/auth/auth-link-redeem) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/oidc/start`](/docs/api/auth/auth-oidc-start) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/oidc`](/docs/api/auth/auth-oidc) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/tma`](/docs/api/auth/auth-tma) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/tma/refresh`](/docs/api/auth/auth-tma-refresh) | Отдельного throttle в коде нет. | | [`POST /api/v1/auth/logout`](/docs/api/auth/auth-logout) | Отдельного throttle в коде нет. | | [`GET /api/v1/auth/sessions`](/docs/api/auth/auth-sessions) | Отдельного throttle в коде нет. | | [`POST /api/v1/auth/sessions/revoke-all`](/docs/api/auth/auth-sessions-revoke-all) | Отдельного throttle в коде нет. | | [`POST /api/v1/auth/password/login`](/docs/api/auth/auth-password-login) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/password/forgot`](/docs/api/auth/auth-password-forgot) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/password/reset`](/docs/api/auth/auth-password-reset) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`GET /api/v1/auth/password`](/docs/api/auth/auth-password-status) | Отдельного throttle в коде нет. | | [`POST /api/v1/auth/password/setup`](/docs/api/auth/auth-password-setup) | 3/10 min/student; защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. | | [`POST /api/v1/auth/password/change`](/docs/api/auth/auth-password-change) | 5/10 min/student. | | [`GET /api/v1/me`](/docs/api/profile/me) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/me/avatar`](/docs/api/profile/me-avatar) | Отдельного throttle в коде нет. | | [`GET /api/v1/onboarding`](/docs/api/profile/onboarding-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`PATCH /api/v1/onboarding`](/docs/api/profile/onboarding-patch) | Отдельного throttle в коде нет. | | [`PUT /api/v1/onboarding/setup`](/docs/api/profile/onboarding-setup) | Отдельного throttle в коде нет. | | [`POST /api/v1/onboarding/submit`](/docs/api/profile/onboarding-submit) | Отдельного throttle в коде нет. | | [`GET /api/v1/plan`](/docs/api/profile/plan-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/sections`](/docs/api/content/sections) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/lessons`](/docs/api/content/lessons) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/lessons/{id}`](/docs/api/content/lesson-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/lessons/{id}/transcript`](/docs/api/content/lesson-transcript) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. | | [`GET /api/v1/efirs`](/docs/api/content/efirs) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/next`](/docs/api/content/next) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/search`](/docs/api/content/search) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. | | [`PUT /api/v1/plan/milestones`](/docs/api/progress/plan-milestones-put) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/progress`](/docs/api/progress/progress-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`PUT /api/v1/progress`](/docs/api/progress/progress-put) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`POST /api/v1/transcribe`](/docs/api/tutor/transcribe) | 1 запись одновременно; по умолчанию 1800 учитываемых секунд/день МСК; списание ceil(durationSec), минимум 10 секунд за вызов провайдера. | | [`GET /api/v1/tutor/messages`](/docs/api/tutor/tutor-messages) | Отдельного throttle в коде нет. | | [`POST /api/v1/tutor/messages`](/docs/api/tutor/tutor-send) | 1 запуск одновременно на студента; сообщения и USD/день МСК из тарифа (`Me.limits`). Общая оценка изображений сообщения ≤10 000 tokens. | | [`GET /api/v1/tutor/facts`](/docs/api/tutor/tutor-facts) | Отдельного throttle в коде нет. | | [`DELETE /api/v1/tutor/facts/{id}`](/docs/api/tutor/tutor-fact-delete) | Отдельного throttle в коде нет. | | [`POST /api/v1/files`](/docs/api/files/files-upload) | параллельные загрузки разрешены. Для PDF – до 2 резерваций на студента суммарно в обработке и ожидании. 20 попыток/день МСК, сброс в 00:00 МСК; отказы после резервирования дневной попытки тоже считаются, кроме отказа из-за занятости сервера: такая попытка возвращается в квоту. Превышение собственных 2 PDF-резерваций попытку расходует. Оба вида занятости дают `429 RATE_LIMITED`, сообщение «Сервер занят, попробуйте через минуту», `retryAfterSec: 60`; исчерпанная дневная квота – `429 DAILY_LIMIT`. Лимит хранения – 200 MiB: все неприкреплённые и прикреплённые за последние 30 суток. | | [`GET /api/v1/files/{id}`](/docs/api/files/files-get) | Отдельного throttle в коде нет. | | [`DELETE /api/v1/files/{id}`](/docs/api/files/files-delete) | Отдельного throttle в коде нет. | | [`GET /api/v1/keys`](/docs/api/keys/keys-list) | Отдельного throttle в коде нет. | | [`POST /api/v1/keys`](/docs/api/keys/keys-create) | До 3 активных персональных ключей; до 10 созданий за день МСК (включая rotation). | | [`POST /api/v1/keys/{id}/rotate`](/docs/api/keys/keys-rotate) | Те же ограничения создания: до 3 активных и 10 созданий/день МСК; заменяемый ключ не занимает дополнительный слот. | | [`DELETE /api/v1/keys/{id}`](/docs/api/keys/keys-revoke) | Отдельного throttle в коде нет. | | [`GET /api/v1/keys/calls`](/docs/api/keys/keys-calls) | Отдельного throttle в коде нет. | | [`GET /api/v1/mentoring/track`](/docs/api/mentoring/mentoring-track) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/track/versions`](/docs/api/mentoring/mentoring-versions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/sessions`](/docs/api/mentoring/mentoring-sessions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/sessions/{sessionId}`](/docs/api/mentoring/mentoring-session) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/decisions`](/docs/api/mentoring/mentoring-decisions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/chat/digests`](/docs/api/mentoring/mentoring-digests) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/chat/messages`](/docs/api/mentoring/mentoring-messages) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /api/v1/mentoring/homework`](/docs/api/mentoring/mentoring-homework) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. | | [`GET /healthz`](/docs/api/ops/healthz) | Отдельного throttle в коде нет. | --- # Схемы JSON Schema всех типов, которые встречаются в публичных эндпоинтах (99). Снимок из [openapi.json](/docs/openapi.json): `$ref: #/components/schemas/Name` – раздел `Name` на этой странице. `required` задаёт обязательные поля; `null` и отсутствие поля различаются. ## ApiCall ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "surface": { "type": "string", "enum": [ "rest", "mcp" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "target": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "latencyMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "client": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "keyId", "surface", "name", "target", "status", "latencyMs", "client", "at" ], "additionalProperties": false } ``` ## ApiCallList ```json { "type": "object", "properties": { "calls": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/ApiCall" } } }, "required": [ "calls" ], "additionalProperties": false } ``` ## ApiKey ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "prefix": { "type": "string", "pattern": "^aos3\\.sk_[A-Za-z0-9_-]{6}$" }, "scopes": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ApiKeyStatus" } }, "required": [ "id", "name", "prefix", "scopes", "createdAt", "expiresAt", "lastUsedAt", "revokedAt", "status" ], "additionalProperties": false } ``` ## ApiKeyCreated ```json { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "pattern": "^aos3\\.sk_[A-Za-z0-9_-]{43}$" } }, "required": [ "key", "secret" ], "additionalProperties": false } ``` ## ApiKeyCreateRequest ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\p{C}\\p{Zl}\\p{Zp}]+$" }, "scopes": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" } } }, "required": [ "name" ], "additionalProperties": false } ``` ## ApiKeyList ```json { "type": "object", "properties": { "keys": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "keys" ], "additionalProperties": false } ``` ## ApiKeyStatus ```json { "type": "string", "enum": [ "active", "expired", "revoked" ] } ``` ## Attachment ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "mime": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/markdown" ] }, "kind": { "type": "string", "enum": [ "image", "pdf", "text" ] }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10485760 } }, "required": [ "id", "name", "mime", "kind", "size" ], "additionalProperties": false } ``` ## CatalogId ```json { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } ``` ## Citation ```json { "type": "object", "properties": { "source": { "type": "integer", "minimum": 0, "maximum": 19 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "source", "start", "end" ], "additionalProperties": false } ``` ## Efir ```json { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LessonCode" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "day": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "upcoming": { "type": "boolean" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "lessonId": { "anyOf": [ { "$ref": "#/components/schemas/LessonCode" }, { "type": "null" } ] } }, "required": [ "id", "title", "day", "minutes", "upcoming", "startsAt", "lessonId" ], "additionalProperties": false } ``` ## EfirList ```json { "type": "object", "properties": { "efirs": { "type": "array", "items": { "$ref": "#/components/schemas/Efir" } } }, "required": [ "efirs" ], "additionalProperties": false } ``` ## ErrorBody ```json { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "minLength": 1, "maxLength": 500 }, "retryAfterSec": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "issues": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ``` ## ErrorCode ```json { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_FAILED", "ONBOARDING_INCOMPLETE", "UNAUTHENTICATED", "LOGIN_INVALID", "LINK_INVALID", "REAUTH_REQUIRED", "CREDENTIAL_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "ORIGIN_REJECTED", "LOGIN_STATE_INVALID", "NO_ENTITLEMENT", "MENTORING_NOT_AVAILABLE", "ONBOARDING_REQUIRED", "NOT_FOUND", "VERSION_CONFLICT", "BUSY", "METHOD_NOT_ALLOWED", "RATE_LIMITED", "DAILY_LIMIT", "GLOBAL_BUDGET", "KEY_LIMIT", "KEY_RATE", "STORAGE_LIMIT", "ENTITLEMENT_UNAVAILABLE", "DICTATION_UNAVAILABLE", "TUTOR_UNAVAILABLE", "INTERNAL" ] } ``` ## Health ```json { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "sha": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" } }, "required": [ "status", "sha" ], "additionalProperties": false } ``` ## KeyScope ```json { "type": "string", "enum": [ "course:read", "profile:read", "progress:write", "tutor:read", "mentoring:read" ] } ``` ## LessonCard ```json { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LessonCode" }, "week": { "type": "integer", "minimum": 0, "maximum": 52 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tools": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "summary": { "type": "string" }, "task": { "type": "string" }, "kind": { "$ref": "#/components/schemas/LessonKind" }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "gated": { "type": "boolean" }, "locked": { "type": "boolean" } }, "required": [ "id", "week", "title", "minutes", "tools", "summary", "task", "kind", "sectionId", "gated", "locked" ], "additionalProperties": false } ``` ## LessonCode ```json { "type": "string", "maxLength": 32, "pattern": "^[a-z0-9]+(\\.[a-z0-9]+)*$" } ``` ## LessonDeck ```json { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "anyOf": [ { "type": "string", "maxLength": 300, "pattern": "^\\/(?!\\/)[A-Za-z0-9._~/-]+$" }, { "type": "string", "format": "uri" } ] } }, "required": [ "title", "url" ], "additionalProperties": false } ``` ## LessonDetail ```json { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LessonCode" }, "week": { "type": "integer", "minimum": 0, "maximum": 52 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tools": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "summary": { "type": "string" }, "task": { "type": "string" }, "kind": { "$ref": "#/components/schemas/LessonKind" }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "gated": { "type": "boolean" }, "locked": { "type": "boolean" }, "video": { "$ref": "#/components/schemas/LessonVideo" }, "konspekt": { "type": "string" }, "timecodes": { "type": "array", "items": { "$ref": "#/components/schemas/Timecode" } }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/LessonPrompt" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/LessonLink" } }, "plan": { "maxItems": 30, "type": "array", "items": { "$ref": "#/components/schemas/LessonPlanStep" } }, "theory": { "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "deck": { "anyOf": [ { "$ref": "#/components/schemas/LessonDeck" }, { "type": "null" } ] } }, "required": [ "id", "week", "title", "minutes", "tools", "summary", "task", "kind", "sectionId", "gated", "locked", "video", "konspekt", "timecodes", "prompts", "links", "plan", "theory", "deck" ], "additionalProperties": false } ``` ## LessonKind ```json { "type": "string", "enum": [ "lesson", "tech", "stream" ] } ``` ## LessonLink ```json { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "format": "uri" }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] } }, "required": [ "title", "url", "description" ], "additionalProperties": false } ``` ## LessonList ```json { "type": "object", "properties": { "lessons": { "type": "array", "items": { "$ref": "#/components/schemas/LessonCard" } } }, "required": [ "lessons" ], "additionalProperties": false } ``` ## LessonPlanStep ```json { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "title", "body" ], "additionalProperties": false } ``` ## LessonPrompt ```json { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "title", "text" ], "additionalProperties": false } ``` ## LessonSource ```json { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "lesson": { "$ref": "#/components/schemas/LessonCode" }, "seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "lesson" } }, "required": [ "label", "lesson", "seconds", "kind" ], "additionalProperties": false } ``` ## LessonVideo ```json { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 32 }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "provider", "url", "durationSec" ], "additionalProperties": false } ``` ## LinkIdentity ```json { "type": "object", "properties": { "target": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 128 }, "username": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_]{4,32}$" }, { "type": "null" } ] }, "avatar": { "anyOf": [ { "type": "string", "maxLength": 87407, "pattern": "^data:image\\/(jpeg|webp);base64,(?:[A-Za-z0-9+/]{4})+(?:[A-Za-z0-9+/][AQgw]==|[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=)?$" }, { "type": "null" } ] } }, "required": [ "displayName", "username", "avatar" ], "additionalProperties": false }, "current": { "anyOf": [ { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 128 }, "username": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_]{4,32}$" }, { "type": "null" } ] } }, "required": [ "displayName", "username" ], "additionalProperties": false }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "target", "current", "expiresAt" ], "additionalProperties": false } ``` ## LinkTokenRequest ```json { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "token" ], "additionalProperties": false } ``` ## MaterialSource ```json { "type": "object", "properties": { "kind": { "type": "string", "const": "material" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "id": { "$ref": "#/components/schemas/CatalogId" } }, "required": [ "kind", "label", "id" ], "additionalProperties": false } ``` ## Me ```json { "type": "object", "properties": { "student": { "$ref": "#/components/schemas/Student" }, "flow": { "type": "string", "const": "agentos3" }, "tier": { "$ref": "#/components/schemas/Tier" }, "mentoring": { "anyOf": [ { "$ref": "#/components/schemas/MentoringKind" }, { "type": "null" } ] }, "offer": { "anyOf": [ { "$ref": "#/components/schemas/Offer" }, { "type": "null" } ] }, "access": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "grace" ] }, "checkedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "state", "checkedAt" ], "additionalProperties": false }, "onboarding": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/OnboardingStatus" }, "done": { "type": "boolean" } }, "required": [ "status", "done" ], "additionalProperties": false }, "planReady": { "type": "boolean" }, "authKind": { "type": "string", "enum": [ "cookie", "tma" ] }, "features": { "type": "object", "properties": { "tutor": { "type": "boolean" }, "agentKeys": { "type": "boolean" }, "dictation": { "type": "boolean" } }, "required": [ "tutor", "agentKeys", "dictation" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "tutorMessagesPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tutorUsdPerDay": { "type": "number", "minimum": 0 } }, "required": [ "tutorMessagesPerDay", "tutorUsdPerDay" ], "additionalProperties": false } }, "required": [ "student", "flow", "tier", "access", "onboarding", "planReady", "authKind", "features", "limits" ], "additionalProperties": false } ``` ## MentoringCoverage ```json { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "gaps": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "reason": { "type": "string", "enum": [ "before_collection", "stopped", "unavailable_voice", "sync_error", "redacted" ] } }, "required": [ "from", "to", "reason" ], "additionalProperties": false } } }, "required": [ "from", "to", "gaps" ], "additionalProperties": false } ``` ## MentoringDecisions ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringStudentDecision" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## MentoringDigests ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringStudentDigest" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## MentoringHomeworkDetails ```json { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 32768 }, "assigneeRole": { "type": "string", "enum": [ "student", "mentor" ] }, "assigneeName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}@<>]*$", "description": "Plain display name of the responsible person when the task is not the student's own. Absent or null means the student." }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "doneCriteria": { "type": "string", "minLength": 1, "maxLength": 32768 }, "status": { "type": "string", "enum": [ "open", "in_progress", "done", "cancelled" ] }, "stage": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "text", "assigneeRole", "dueAt", "doneCriteria", "status", "stage" ], "additionalProperties": false } ``` ## MentoringHomeworkTask ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "$ref": "#/components/schemas/MentoringHomeworkDetails" }, "sessionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "id", "updatedAt", "refs", "details", "sessionId", "decisionId", "dependencies" ], "additionalProperties": false } ``` ## MentoringKind ```json { "type": "string", "enum": [ "curator", "dashi" ] } ``` ## MentoringMessages ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringStudentMessage" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## MentoringPersonalTrack ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "version": { "$ref": "#/components/schemas/MentoringVersion" } }, "required": [ "id", "title", "updatedAt", "version" ], "additionalProperties": false } ``` ## MentoringSegment ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "speakerRole": { "type": "string", "enum": [ "student", "mentor" ] }, "text": { "type": "string", "maxLength": 8192 }, "status": { "$ref": "#/components/schemas/MentoringTranscriptStatus" }, "quality": { "type": "string", "enum": [ "verified", "uncertain", "redacted" ] } }, "required": [ "ordinal", "startSeconds", "endSeconds", "speakerRole", "text", "status" ], "additionalProperties": false } }, "required": [ "id", "updatedAt", "refs", "details" ], "additionalProperties": false } ``` ## MentoringSessionRead ```json { "type": "object", "properties": { "view": { "type": "string", "enum": [ "summary", "transcript" ] }, "session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "kind": { "type": "string", "enum": [ "call", "consultation" ] }, "durationSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "completed", "cancelled" ] }, "summary": { "type": "string", "maxLength": 32768 }, "transcriptStatus": { "$ref": "#/components/schemas/MentoringTranscriptStatus" }, "hostName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}@<>]*$" }, "recordingUrl": { "description": "HTTPS recording link. Allowed exact hosts: kinescope.io.", "type": "string", "maxLength": 2048, "format": "uri" }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}<>]*$" }, "brief": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}<>]*$" } }, "required": [ "startsAt", "kind", "durationSeconds", "status", "transcriptStatus" ], "additionalProperties": false }, "trackVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "id", "updatedAt", "refs", "details", "trackVersionId" ], "additionalProperties": false }, "transcriptStatus": { "$ref": "#/components/schemas/MentoringTranscriptStatus" }, "oversizedSegment": { "type": "boolean" }, "items": { "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/MentoringSegment" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "view", "session" ], "additionalProperties": false } ``` ## MentoringSessions ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringStudentSession" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## MentoringStudentDecision ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 32768 }, "authorRole": { "type": "string", "enum": [ "student", "mentor" ] }, "status": { "type": "string", "enum": [ "proposed", "unconfirmed", "confirmed", "superseded", "cancelled" ] }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "text", "authorRole", "status", "dueAt" ], "additionalProperties": false }, "sessionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "supersedesId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "id", "updatedAt", "refs", "details", "sessionId", "supersedesId" ], "additionalProperties": false } ``` ## MentoringStudentDigest ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "timezone": { "type": "string", "const": "Europe/Moscow" }, "summary": { "type": "string", "minLength": 1, "maxLength": 32768 }, "coverage": { "$ref": "#/components/schemas/MentoringCoverage" } }, "required": [ "date", "timezone", "summary", "coverage" ], "additionalProperties": false } }, "required": [ "id", "updatedAt", "refs", "details" ], "additionalProperties": false } ``` ## MentoringStudentHomework ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringHomeworkTask" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## MentoringStudentMessage ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "speakerRole": { "type": "string", "enum": [ "student", "mentor" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 32768 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "at", "speakerRole", "text", "revision" ], "additionalProperties": false } }, "required": [ "id", "updatedAt", "refs", "details" ], "additionalProperties": false } ``` ## MentoringStudentSession ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "kind": { "type": "string", "enum": [ "call", "consultation" ] }, "durationSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "completed", "cancelled" ] }, "summary": { "type": "string", "maxLength": 32768 }, "transcriptStatus": { "$ref": "#/components/schemas/MentoringTranscriptStatus" }, "hostName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}@<>]*$" }, "recordingUrl": { "description": "HTTPS recording link. Allowed exact hosts: kinescope.io.", "type": "string", "maxLength": 2048, "format": "uri" }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}<>]*$" }, "brief": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[^\\p{Cc}\\p{Cf}\\p{Cs}<>]*$" } }, "required": [ "startsAt", "kind", "durationSeconds", "status", "summary", "transcriptStatus" ], "additionalProperties": false }, "trackVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "id", "updatedAt", "refs", "details", "trackVersionId" ], "additionalProperties": false } ``` ## MentoringTranscriptStatus ```json { "type": "string", "enum": [ "not_provided", "consent_required", "processing", "ready", "failed", "redacted" ] } ``` ## MentoringVersion ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "document", "message", "segment", "recording" ] }, "position": { "type": "object", "properties": { "startSeconds": { "type": "number", "minimum": 0 }, "endSeconds": { "type": "number", "minimum": 0 }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false } }, "details": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 262144 }, "sections": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 256 }, "markdown": { "type": "string", "minLength": 1, "maxLength": 32768 } }, "required": [ "title", "markdown" ], "additionalProperties": false } }, "stages": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_.:-]+$" }, "title": { "type": "string", "maxLength": 256 }, "status": { "type": "string", "enum": [ "planned", "active", "done" ] } }, "required": [ "id", "title", "status" ], "additionalProperties": false } }, "metrics": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 256 }, "value": { "type": "string", "maxLength": 256 } }, "required": [ "label", "value" ], "additionalProperties": false } }, "changes": { "type": "string", "maxLength": 32768 } }, "required": [ "markdown", "sections", "stages", "metrics", "changes" ], "additionalProperties": false } }, "required": [ "id", "updatedAt", "refs", "details" ], "additionalProperties": false } ``` ## MentoringVersions ```json { "type": "object", "properties": { "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MentoringVersion" } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor", "updatedAt" ], "additionalProperties": false } ``` ## NextLesson ```json { "type": "object", "properties": { "lesson": { "anyOf": [ { "$ref": "#/components/schemas/LessonCard" }, { "type": "null" } ] }, "reason": { "type": "string", "enum": [ "continue", "next", "onboarding", "done" ] } }, "required": [ "lesson", "reason" ], "additionalProperties": false } ``` ## Offer ```json { "type": "string", "enum": [ "tutoring" ] } ``` ## OidcCallbackRequest ```json { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 512 }, "state": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "code", "state" ], "additionalProperties": false } ``` ## OidcStartResponse ```json { "type": "object", "properties": { "authorizeUrl": { "type": "string", "format": "uri" } }, "required": [ "authorizeUrl" ], "additionalProperties": false } ``` ## Onboarding ```json { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 2 }, "status": { "$ref": "#/components/schemas/OnboardingStatus" }, "step": { "type": "integer", "minimum": 0, "maximum": 12 }, "answers": { "$ref": "#/components/schemas/OnboardingDraft" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "schemaVersion", "status", "step", "answers", "completedAt" ], "additionalProperties": false } ``` ## OnboardingDraft ```json { "type": "object", "properties": { "role": { "anyOf": [ { "type": "string", "enum": [ "Основатель бизнеса", "Руководитель команды", "Эксперт / фрилансер", "Работаю в найме" ] }, { "type": "string", "const": "" } ] }, "business": { "type": "string", "maxLength": 2000 }, "scenario": { "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "Продажи и заявки", "Контент и маркетинг", "Поддержка клиентов", "Аналитика бизнеса", "Личный помощник", "Документы и отчёты", "Операции и задачи команды", "Найм и HR", "Финансы и учёт", "Исследования и поиск информации", "Обучение команды", "Разработка и автоматизация", "Другое" ] } }, "scenarioOther": { "type": "string", "maxLength": 200 }, "level": { "anyOf": [ { "type": "string", "enum": [ "Только пробую нейросети", "Пользуюсь ChatGPT/Claude каждый день", "Писал промпты, настраивал GPTs или проекты", "Собирал ботов и автоматизации (n8n, Make, Zapier)", "Пишу код или работал с Claude Code / Cursor / Codex" ] }, { "type": "string", "const": "" } ] }, "aiTools": { "maxItems": 14, "type": "array", "items": { "type": "string", "enum": [ "ChatGPT", "Claude", "Gemini", "Perplexity", "DeepSeek", "GigaChat", "YandexGPT / Алиса", "Cursor", "Claude Code", "Codex", "n8n / Make / Zapier", "Telegram-боты", "Пока ничего не использую", "Другое" ] } }, "aiToolsOther": { "type": "string", "maxLength": 200 }, "setup": { "anyOf": [ { "type": "string", "enum": [ "hermes", "codex", "claude", "plugin" ] }, { "type": "string", "const": "" } ] }, "budget": { "anyOf": [ { "type": "string", "enum": [ "lt50", "50_100", "100_200", "200_500", "500p" ] }, { "type": "string", "const": "" } ] }, "tools": { "maxItems": 49, "type": "array", "items": { "type": "string", "enum": [ "Telegram", "WhatsApp", "VK", "Max", "Instagram", "YouTube", "Дзен", "amoCRM", "Битрикс24", "RetailCRM", "YCLIENTS", "1С", "МойСклад", "Контур", "Т-Бизнес", "СберБизнес", "Точка", "Эвотор", "Google Docs и Sheets", "Яндекс Документы и Диск", "Excel", "Notion", "Yonote", "Miro", "Trello", "Яндекс Трекер", "Kaiten", "WEEEK", "Wildberries", "Ozon", "Яндекс Маркет", "Авито", "Тильда", "WordPress", "Яндекс Директ", "Яндекс Метрика", "VK Реклама", "GetCourse", "Unisender", "Gmail", "Яндекс 360", "Google Календарь", "Zoom", "Телемост", "n8n", "Make", "Zapier", "Albato", "Другое" ] } }, "toolsOther": { "type": "string", "maxLength": 200 }, "time": { "anyOf": [ { "type": "string", "enum": [ "1–3 часа в неделю", "3–5 часов в неделю", "5–10 часов в неделю", "Больше 10 часов" ] }, { "type": "string", "const": "" } ] }, "hardware": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "Есть сервер (VPS)", "Платный публичный VPN", "Свой VPN", "Есть только компьютер", "Нужна помощь с настройкой" ] } }, "os": { "anyOf": [ { "type": "string", "enum": [ "macOS", "Windows", "Linux" ] }, { "type": "string", "const": "" } ] }, "goal": { "type": "string", "maxLength": 2000 }, "about": { "type": "string", "maxLength": 2000 }, "socialsPersonal": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" } }, "socialsBusiness": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" } }, "website": { "anyOf": [ { "$ref": "#/components/schemas/Website" }, { "type": "string", "const": "" } ] } }, "additionalProperties": false } ``` ## OnboardingDraftPatch ```json { "type": "object", "properties": { "role": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "Основатель бизнеса", "Руководитель команды", "Эксперт / фрилансер", "Работаю в найме" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "business": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "scenario": { "anyOf": [ { "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "Продажи и заявки", "Контент и маркетинг", "Поддержка клиентов", "Аналитика бизнеса", "Личный помощник", "Документы и отчёты", "Операции и задачи команды", "Найм и HR", "Финансы и учёт", "Исследования и поиск информации", "Обучение команды", "Разработка и автоматизация", "Другое" ] } }, { "type": "null" } ] }, "scenarioOther": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "level": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "Только пробую нейросети", "Пользуюсь ChatGPT/Claude каждый день", "Писал промпты, настраивал GPTs или проекты", "Собирал ботов и автоматизации (n8n, Make, Zapier)", "Пишу код или работал с Claude Code / Cursor / Codex" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "aiTools": { "anyOf": [ { "maxItems": 14, "type": "array", "items": { "type": "string", "enum": [ "ChatGPT", "Claude", "Gemini", "Perplexity", "DeepSeek", "GigaChat", "YandexGPT / Алиса", "Cursor", "Claude Code", "Codex", "n8n / Make / Zapier", "Telegram-боты", "Пока ничего не использую", "Другое" ] } }, { "type": "null" } ] }, "aiToolsOther": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "setup": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "hermes", "codex", "claude", "plugin" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "budget": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "lt50", "50_100", "100_200", "200_500", "500p" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "tools": { "anyOf": [ { "maxItems": 49, "type": "array", "items": { "type": "string", "enum": [ "Telegram", "WhatsApp", "VK", "Max", "Instagram", "YouTube", "Дзен", "amoCRM", "Битрикс24", "RetailCRM", "YCLIENTS", "1С", "МойСклад", "Контур", "Т-Бизнес", "СберБизнес", "Точка", "Эвотор", "Google Docs и Sheets", "Яндекс Документы и Диск", "Excel", "Notion", "Yonote", "Miro", "Trello", "Яндекс Трекер", "Kaiten", "WEEEK", "Wildberries", "Ozon", "Яндекс Маркет", "Авито", "Тильда", "WordPress", "Яндекс Директ", "Яндекс Метрика", "VK Реклама", "GetCourse", "Unisender", "Gmail", "Яндекс 360", "Google Календарь", "Zoom", "Телемост", "n8n", "Make", "Zapier", "Albato", "Другое" ] } }, { "type": "null" } ] }, "toolsOther": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "time": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "1–3 часа в неделю", "3–5 часов в неделю", "5–10 часов в неделю", "Больше 10 часов" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "hardware": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "Есть сервер (VPS)", "Платный публичный VPN", "Свой VPN", "Есть только компьютер", "Нужна помощь с настройкой" ] } }, { "type": "null" } ] }, "os": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "macOS", "Windows", "Linux" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "goal": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "about": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "socialsPersonal": { "anyOf": [ { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" } }, { "type": "null" } ] }, "socialsBusiness": { "anyOf": [ { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" } }, { "type": "null" } ] }, "website": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/Website" }, { "type": "string", "const": "" } ] }, { "type": "null" } ] } }, "additionalProperties": false } ``` ## OnboardingPatchRequest ```json { "type": "object", "properties": { "step": { "type": "integer", "minimum": 0, "maximum": 12 }, "answers": { "$ref": "#/components/schemas/OnboardingDraftPatch" } }, "required": [ "step", "answers" ], "additionalProperties": false } ``` ## OnboardingSetupRequest ```json { "type": "object", "properties": { "setup": { "$ref": "#/components/schemas/SetupId" } }, "required": [ "setup" ], "additionalProperties": false } ``` ## OnboardingStatus ```json { "type": "string", "enum": [ "draft", "in_review", "plan_ready" ] } ``` ## PasswordChangeRequest ```json { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 128 }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } ``` ## PasswordForgotRequest ```json { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } ``` ## PasswordLoginRequest ```json { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "email", "password" ], "additionalProperties": false } ``` ## PasswordResetRequest ```json { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "token", "password" ], "additionalProperties": false } ``` ## PasswordResetResponse ```json { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } ``` ## PasswordSetupRequest ```json { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "orderEmail": { "type": "boolean", "const": true }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false } ``` ## PasswordStatus ```json { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "hasPassword": { "type": "boolean" }, "mailEnabled": { "type": "boolean" }, "orderEmail": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "orderEmailMasked": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^[^@\\s*]{0,2}\\*\\*\\*@[^@\\s*.]{0,2}\\*\\*\\*\\.[^@\\s*.]{1,63}$" }, { "type": "null" } ] } }, "required": [ "email", "hasPassword", "mailEnabled", "orderEmail", "orderEmailMasked" ], "additionalProperties": false } ``` ## PlanContent ```json { "type": "object", "properties": { "letter": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "paragraphs": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 3000 } } }, "required": [ "title", "paragraphs" ], "additionalProperties": false }, "stack": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "setup": { "$ref": "#/components/schemas/SetupId" }, "recommended": { "type": "boolean" }, "note": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "setup", "recommended", "note" ], "additionalProperties": false } }, "dashboards": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "value": { "type": "string", "minLength": 1, "maxLength": 20 }, "label": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "name", "value", "label" ], "additionalProperties": false } }, "repos": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "title", "url", "description" ], "additionalProperties": false } }, "skills": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "type": "string", "minLength": 1, "maxLength": 3000 }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "title", "description", "url" ], "additionalProperties": false } }, "project": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "title", "description" ], "additionalProperties": false }, "milestones": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } } }, "required": [ "letter", "stack", "dashboards", "repos", "skills", "project", "milestones" ], "additionalProperties": false } ``` ## PlanMilestonesUpdateRequest ```json { "type": "object", "properties": { "milestonesDone": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 11 } }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "milestonesDone", "expectedVersion" ], "additionalProperties": false } ``` ## PlanResponse ```json { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/OnboardingStatus" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/PlanContent" }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "status", "plan", "version", "publishedAt" ], "additionalProperties": false } ``` ## Progress ```json { "type": "object", "properties": { "completed": { "type": "array", "items": { "$ref": "#/components/schemas/LessonCode" } }, "positions": { "type": "object", "propertyNames": { "$ref": "#/components/schemas/LessonCode" }, "additionalProperties": { "type": "number", "minimum": 0 } }, "homework": { "type": "object", "propertyNames": { "$ref": "#/components/schemas/LessonCode" }, "additionalProperties": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "sent": { "type": "boolean" } }, "required": [ "text", "sent" ], "additionalProperties": false } }, "milestonesDone": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "required": [ "completed", "positions", "homework", "milestonesDone" ], "additionalProperties": false } ``` ## ProgressUpdateRequest ```json { "type": "object", "properties": { "lessonId": { "$ref": "#/components/schemas/LessonCode" }, "positionSec": { "type": "number", "minimum": 0, "maximum": 86400 }, "completed": { "type": "boolean" }, "homework": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "sent": { "type": "boolean" } }, "required": [ "text", "sent" ], "additionalProperties": false } }, "required": [ "lessonId" ], "additionalProperties": false } ``` ## RevokeAllResponse ```json { "type": "object", "properties": { "revoked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "revoked" ], "additionalProperties": false } ``` ## SearchResults ```json { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "lesson": { "$ref": "#/components/schemas/LessonCode" }, "seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "title": { "type": "string" }, "snippet": { "type": "string", "maxLength": 500 } }, "required": [ "label", "lesson", "seconds", "title", "snippet" ], "additionalProperties": false } } }, "required": [ "query", "results" ], "additionalProperties": false } ``` ## Section ```json { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "kind": { "type": "string", "enum": [ "efirs", "pretraining", "week", "tech", "skills" ] }, "number": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "lessons": { "type": "array", "items": { "$ref": "#/components/schemas/LessonCard" } } }, "required": [ "id", "kind", "number", "title", "lessons" ], "additionalProperties": false } ``` ## SectionList ```json { "type": "object", "properties": { "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } } }, "required": [ "sections" ], "additionalProperties": false } ``` ## SessionInfo ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "cookie", "tma" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "device": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "current": { "type": "boolean" } }, "required": [ "id", "kind", "createdAt", "lastSeenAt", "device", "current" ], "additionalProperties": false } ``` ## SessionList ```json { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfo" } } }, "required": [ "sessions" ], "additionalProperties": false } ``` ## SetupId ```json { "type": "string", "enum": [ "hermes", "codex", "claude", "plugin" ] } ``` ## SkillSource ```json { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "id": { "$ref": "#/components/schemas/CatalogId" } }, "required": [ "kind", "label", "id" ], "additionalProperties": false } ``` ## SocialLink ```json { "anyOf": [ { "$ref": "#/components/schemas/Website" }, { "type": "string", "pattern": "^@(?=[A-Za-z0-9_.]*[A-Za-z])(?![A-Za-z0-9_.]*\\d{7})[A-Za-z0-9_.]{2,64}$" } ] } ``` ## Source ```json { "oneOf": [ { "$ref": "#/components/schemas/LessonSource" }, { "$ref": "#/components/schemas/SkillSource" }, { "$ref": "#/components/schemas/MaterialSource" } ] } ``` ## Student ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tgId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "username": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_]{4,32}$" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "pattern": "^\\/api\\/v1\\/me\\/avatar\\?v=[0-9a-f]{32}$" }, { "type": "null" } ] } }, "required": [ "id", "tgId", "name", "username", "avatarUrl" ], "additionalProperties": false } ``` ## Tier ```json { "type": "string", "enum": [ "group", "personal" ] } ``` ## Timecode ```json { "type": "object", "properties": { "t": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "t", "label", "text" ], "additionalProperties": false } ``` ## TmaExchangeRequest ```json { "type": "object", "properties": { "initData": { "type": "string", "minLength": 1, "maxLength": 8192 } }, "required": [ "initData" ], "additionalProperties": false } ``` ## TmaExchangeResponse ```json { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TmaToken" }, "me": { "$ref": "#/components/schemas/Me" } }, "required": [ "session", "me" ], "additionalProperties": false } ``` ## TmaToken ```json { "type": "object", "properties": { "token": { "type": "string", "pattern": "^aos3\\.tt_[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "absoluteExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "token", "expiresAt", "absoluteExpiresAt" ], "additionalProperties": false } ``` ## TranscribeResponse ```json { "type": "object", "properties": { "text": { "type": "string", "maxLength": 20000 }, "durationSec": { "type": "number", "minimum": 0 }, "remainingSecToday": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "text", "durationSec", "remainingSecToday" ], "additionalProperties": false } ``` ## Transcript ```json { "type": "object", "properties": { "lessonId": { "$ref": "#/components/schemas/LessonCode" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "t", "text" ], "additionalProperties": false } } }, "required": [ "lessonId", "segments" ], "additionalProperties": false } ``` ## TutorFact ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fact": { "type": "string", "minLength": 1, "maxLength": 500 }, "category": { "type": "string", "enum": [ "goal", "setup", "preference", "progress", "other" ] }, "createdBy": { "type": "string", "enum": [ "tutor", "student" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "fact", "category", "createdBy", "createdAt" ], "additionalProperties": false } ``` ## TutorFacts ```json { "type": "object", "properties": { "facts": { "type": "array", "items": { "$ref": "#/components/schemas/TutorFact" } } }, "required": [ "facts" ], "additionalProperties": false } ``` ## TutorMessage ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string", "maxLength": 65536 }, "sources": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "parts": { "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/TutorPart" } }, "citations": { "default": [], "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "error": { "type": "boolean" }, "feedback": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "attachments": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "role", "text", "sources", "citations", "error", "feedback", "attachments", "createdAt" ], "additionalProperties": false } ``` ## TutorMessagesPage ```json { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/TutorMessage" } }, "nextBefore": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "messages", "nextBefore" ], "additionalProperties": false } ``` ## TutorPart ```json { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "progress" }, "lessonsDone": { "type": "integer", "minimum": 0, "maximum": 10000 }, "lessonsTotal": { "type": "integer", "minimum": 0, "maximum": 10000 }, "milestonesDone": { "type": "integer", "minimum": 0, "maximum": 10000 }, "milestonesTotal": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "type", "lessonsDone", "lessonsTotal", "milestonesDone", "milestonesTotal" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lesson" }, "code": { "$ref": "#/components/schemas/LessonCode" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "positionSec": { "type": "integer", "minimum": 0, "maximum": 86400 }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "required": [ "type", "code", "title", "positionSec", "durationSec" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "checklist" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 300 }, "done": { "type": "boolean" } }, "required": [ "text", "done" ], "additionalProperties": false } } }, "required": [ "type", "title", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "compare" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "options": { "minItems": 2, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "points": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } } }, "required": [ "name", "points" ], "additionalProperties": false } } }, "required": [ "type", "title", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "chips" }, "questions": { "minItems": 2, "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "required": [ "type", "questions" ], "additionalProperties": false } ] } ``` ## TutorSendRequest ```json { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "text": { "type": "string", "maxLength": 4000 }, "attachments": { "maxItems": 4, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "requestId", "text" ], "additionalProperties": false } ``` ## TutorSendResponse ```json { "type": "object", "properties": { "userMessage": { "$ref": "#/components/schemas/TutorMessage" }, "reply": { "$ref": "#/components/schemas/TutorMessage" }, "messagesLeftToday": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "userMessage", "reply", "messagesLeftToday" ], "additionalProperties": false } ``` ## Upload ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "mime": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/markdown" ] }, "kind": { "type": "string", "enum": [ "image", "pdf", "text" ] }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10485760 }, "width": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 4096 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 4096 }, { "type": "null" } ] }, "pages": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 20 }, { "type": "null" } ] }, "textTruncated": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "mime", "kind", "size", "width", "height", "pages", "textTruncated", "createdAt" ], "additionalProperties": false } ``` ## Website ```json { "type": "string", "maxLength": 500, "format": "uri" } ``` --- # Изменения Изменения, которые касаются студентов и их агентов. Новые записи – сверху. ## 2026-10-25 – Публичная документация - Документация на `/docs`: обзор, быстрый старт, справочник REST по разделам, инструменты MCP, OAuth, ошибки, лимиты, схемы. - Для ИИ-агентов: `/docs/llms.txt`, `/docs/llms-full.txt`, markdown-версия каждой страницы (`.md`) и публичный `/docs/openapi.json`. ## 2026-10-21 – Личный менторинг - Новый scope `mentoring:read`: выдаётся только явно и никогда не добавляется к существующим ключам и подключениям. - Восемь эндпоинтов [`/api/v1/mentoring/*`](/docs/api/mentoring) и восемь инструментов MCP для тарифа «Лично»: трек, встречи, решения, задания, сводки и сообщения чата с ментором. - Новый код ошибки `MENTORING_NOT_AVAILABLE` (403) для тарифа «Группа». ## 2026-10-21 – Запись прогресса через MCP и история тьютора - Инструменты `aos_mark_lesson` и `aos_update_plan_milestone` (scope `progress:write`) и `aos_get_tutor_history` (новый scope `tutor:read`, только явно). - [`PUT /api/v1/plan/milestones`](/docs/api/progress/plan-milestones-put) требует `expectedVersion` и возвращает `VERSION_CONFLICT`, если план успели опубликовать заново. - `PUT /api/v1/progress`: `completed: false` и отсутствие поля сохраняют отметку; повторная отметка сохраняет исходную дату завершения. - Ключи по умолчанию по-прежнему получают `course:read` и `profile:read`.