Документация API

Маршруты раздела

Подключение

MCP endpoint — https://latorn.ru/api/mcp. Он принимает только POST и только персональный токен в заголовке Authorization: Bearer …. Cookie-сессия браузера здесь не работает.

Создайте отдельный токен в Настройки → API-токены (/profile/security?section=api), выберите только нужные курсы, минимальные права и срок действия. Не помещайте секрет в публичный JavaScript.
К одному токену можно привязать не более 100 уникальных курсов. MCP принимает только несжатые запросы с корректным Content-Length до 9 MiB.

{
  "mcpServers": {
    "latorn": {
      "type": "http",
      "url": "https://latorn.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer ${LATORN_API_TOKEN}"
      }
    }
  }
}

Названия полей конфигурации могут отличаться у MCP-клиентов; неизменны URL и Bearer-заголовок. Сервер stateless: Mcp-Session-Id не выдаётся, а PAT и живые права проверяются на каждом запросе.

Что можно поручить агенту

• latorn_list_courses, latorn_get_course, latorn_get_course_content — читать разрешённые курсы;
• latorn_list_task_seo_candidates — постранично просматривать задачи этих курсов по курсу, уроку, типу и статусу индексации: полное публичное условие, возможность гостевой проверки и ссылку на индексируемый урок без скрытых тестов и ответов;
• latorn_update_task_seo — сохранять slug, заголовок, описание и пояснение одной задачи и явно включать или выключать её индексацию;
• latorn_get_course_sales_insights и latorn_get_portfolio_sales_insights — анализировать только агрегаты продаж и воронки;
• latorn_list_course_promos, latorn_bulk_upsert_course_promos — читать и атомарно сохранять/деактивировать промокоды разрешённого курса;
• latorn_list_broadcast_drafts, latorn_save_broadcast_draft — актуальному администратору читать и готовить собственный EDITOR/FULL_HTML DRAFT со встроенным consent-only сегментом и фильтрами курсов; получателей и preview нет, BUILDER меняется только в UI Latorn;
• latorn_create_draft_course — создать бесплатный неопубликованный черновик;
• latorn_set_draft_content — атомарно наполнить пустой черновик полной иерархией разделов, уроков и шагов;
• latorn_update_course_metadata — изменить учебные и SEO-метаданные без цены, публикации, владельца и доступов;
• latorn_create_section, latorn_update_section, latorn_create_lesson, latorn_update_lesson;
• latorn_create_step, latorn_update_step — через штатную валидацию блока, с настройкой maxPoints и lateMaxPoints; те же баллы можно задать каждому шагу первоначального latorn_set_draft_content;
• latorn_reorder_content — атомарно применить полный снимок порядка уроков или шагов;
• latorn_request_course_publish — подготовить одноразовую ссылку на подтверждение;
• latorn_get_course_publish_request — проверить состояние запроса публикации.

Для каждого course-вызова одновременно нужны действующий PAT, подходящий scope, курс в courseIds, актуальная capability, незаблокированный аккаунт и неудалённый курс. Broadcast-draft вызовы вместо course binding требуют отдельный BROADCAST_DRAFTS_WRITE, актуальную роль ADMIN и отсутствие platform FULL ban. В списке существующий BUILDER помечается editableViaMcp=false; попытка обновления отвечает BROADCAST_BUILDER_DRAFT_UNSUPPORTED, не стирая block state. REVENUE_READ, COURSES_PUBLISH, PROMOS_WRITE и BROADCAST_DRAFTS_WRITE выдаются отдельно и не входят в рекомендуемый набор по умолчанию.
Администратор может добавить право ADMIN_COURSE_EDIT, найти курсы других авторов и привязать к токену только нужные ID. Для чтения и правки также выберите обычные COURSES_READ, COURSES_WRITE, CONTENT_READ, CONTENT_WRITE или MEDIA_WRITE. Роль администратора и блокировки повторно проверяются на каждом вызове. Это право открывает материалы и безопасные учебные/SEO-метаданные выбранных курсов. Все доступные права можно сочетать в одном токене, включая просмотр всех задач, подборки, промокоды и черновики рассылок. Каждая операция проверяет своё право и актуальные разрешения отдельно: просмотр всех задач не даёт редактировать все курсы, а редактирование материалов само по себе не даёт доступ к деньгам, публикации, владельцу, пользователям или доступам.
latorn_get_course возвращает отдельные nullable-поля seoTitle и seoDescription. Их можно передать при создании через latorn_create_draft_course и менять через latorn_update_course_metadata: до 120 и 160 символов соответственно; null возвращает автоматические метаданные из обычного названия и описания курса. Цена, slug, публикация и доступы при этом не меняются.
latorn_get_course_content возвращает у каждого урока slug, seoTitle, seoDescription и isIndexable. Те же поля принимают latorn_create_lesson, latorn_update_lesson и уроки атомарного latorn_set_draft_content; они используют те же нормализацию, course-scoped уникальность и PUBLIC-инвариант, что обычный Lesson API. MCP по-прежнему не публикует курс: после человеческого подтверждения индексируемая страница урока будет доступна по /courses/[courseSlug]/lessons/[lessonSlug].

Для отбора отдельных задач вызовите latorn_list_task_seo_candidates с необязательными courseId, lessonId, type, status (published или unpublished), offset и limit до 100. Список охватывает все задачи выбранных курсов; отдельные задачи платного курса можно публиковать, не открывая урок и остальные материалы. Для каждой задачи он показывает ID, полное безопасное условие без скрытых тестов и ответов, курс и урок, гостевую проверку и ссылку на индексируемый урок. Если задача уже целиком показана в нём, стоит отметка duplicateLessonContent. latorn_update_task_seo меняет только один заданный stepId; isIndexable=true открывает страницу /tasks/[courseSlug]/[taskSlug] лишь для опубликованного курса любой цены, открытого раздела и задачи с рабочей гостевой проверкой без конфликта с уроком. По умолчанию индексация выключена. Отключение закрывает страницу и убирает её из sitemap; впервые использованный slug остаётся закреплённым.
Для отдельной страницы подходят автоматически проверяемые CODE, CHOICE, NUMBER, FREE_TEXT, SORTING и MATCHING. Пассивные TEXT/VIDEO и ручной REVIEW публиковать как задачи нельзя. Выбор, сортировка и сопоставление возвращают в публичном условии непрозрачные ID вариантов. Гостевой POST /api/public-practice принимает {stepId,answer} для не-кодовых форматов; после проверки он возвращает только статус, не ключ ответа.
В latorn_bulk_upsert_course_promos каждый upsert передаёт полное состояние промокода. Поля startsAt, expiresAt, isActive, autoApply и maxRedemptions обязательны; для пустой даты или лимита укажите null. Пропущенное поле отклоняется, поэтому существующие срок, активность и лимит не сбрасываются случайно. Promo-ответы содержат максимум 500 строк и отдельные total/truncated.
Для защиты endpoint действует 240 запросов в минуту на IP до проверки токена и 120 запросов в минуту на PAT после проверки. Сейчас store локальный/подключаемый через abstraction, поэтому это не обещание распределённого лимита между несколькими инстансами.

Индексируемый публичный урок открывает все свои поддерживаемые задачи для гостевого решения прямо на странице урока, в том числе в платном курсе. Отдельно включать индексацию каждого шага и задавать ему slug не нужно. Остальные уроки курса остаются закрытыми; отдельные страницы задач автоматически не создаются.

От анализа до публикации

1. При необходимости агент анализирует продажи одного курса или портфеля. Ответ содержит только агрегаты — без имён, email, user id, provider/payment id и сырых операций; внутренние anonymousId, sessionId и User-Agent также не выдаются.
2. Агент создаёт черновик, наполняет его через latorn_set_draft_content и точечно редактирует содержание.
3. Когда результат готов, latorn_request_course_publish возвращает ссылку, но ничего не публикует.
4. Владелец того же PAT входит в Latorn, проверяет точный снимок и вводит ОПУБЛИКОВАТЬ.
5. Агент опрашивает состояние через latorn_get_course_publish_request.

Ссылка действует 15 минут и привязана к пользователю, PAT и точному снимку курса. Любое изменение курса делает запрос устаревшим — после правок нужна новая ссылка. MCP не может подтвердить её за человека.

Полный импорт черновика

latorn_set_draft_content работает только с пустым неопубликованным черновиком. Он либо создаёт всю иерархию, либо не создаёт ничего. Точно повторённый нормализованный снимок возвращает прежние id и replayed: true; другое существующее содержание даёт 409 DRAFT_CONTENT_ALREADY_EXISTS без удаления и перезаписи.

Один запрос ограничен 8 MiB JSON, 50 разделами, 500 уроками, 2000 шагами и общей длиной заголовков 120 000 символов. Каждый шаг проходит обычную server-side validation Latorn.
Для аналитики один портфель ограничен 100 курсами, один запрос — 25 000 платежей и 50 000 событий. При превышении вернётся 413 SALES_INSIGHTS_TOO_LARGE: уменьшите период или число курсов.

Аналитика отдельно показывает путь из CTA платного курса и бесплатного старта: показ и отправку auth-формы, безопасный результат, регистрацию, текущее подтверждение почты и существующие checkout/payment либо enrollment/progress этапы. Подтверждение почты не дублируется отдельным событием. Тип клиента ограничен telegram_webview | regular_browser | unknown; устройство, браузер и ОС также используют только закрытые нормализованные категории.

Разбивки по каналам, промокодам, auth-result и client context не включают URL, email и телефоноподобные значения. Ненулевые auth/client/payment cells меньше трёх скрываются или заменяются на null. Это не даёт агрегатам раскрывать отдельного покупателя или восстановить pre-auth идентификаторы.

Те же действия доступны через защищённый REST API: GET /api/task-seo с фильтрами courseId, lessonId, type, status, offset, limit и PATCH /api/task-seo с JSON-полями конкретной задачи. Оба метода требуют Bearer PAT. Обычное право CONTENT_READ показывает задачи только выбранных в токене курсов; отдельное admin-only TASK_SEO_READ позволяет просмотреть все курсы, но не менять SEO. Для изменения нужны CONTENT_WRITE и актуальное право редактирования соответствующего курса.

Тематические подборки задач

Публичные задачи автоматически связаны со страницами курса и публичного урока, списками /tasks и /tasks/[courseSlug], родственными заданиями и sitemap. Пагинация — ?page=2, по 24 задачи; при снятии задачи или курса с публикации ссылки исчезают без отдельного запуска индексации.

Для подборок администратор отдельно выдаёт PAT право TASK_COLLECTIONS_WRITE (без привязки к курсам). Команды latorn_list_task_collections и latorn_save_task_collection работают так же, как GET /api/task-collections и PUT /api/task-collections. Для списка доступны id, offset и limit до 100.

Сохранение принимает полное состояние: title (2–200), slug (после нормализации 2–80), seoTitle (до 120 или null), seoDescription (до 160 или null), intro (Markdown до 20 000), stepIds (до 500 уникальных существующих заданий в нужном порядке), isPublished (true/false). Без id создаётся новая подборка. Для изменения нужны id и expectedVersion из результата чтения; конфликт даёт 409 без частичной записи.

isPublished=true явно публикует одну подборку по /task-collections/[slug], но не её задачи или курсы. Для публикации нужна хотя бы одна реально публичная задача. Неиндексируемые задачи могут храниться в составе, но не видны гостям. Если все задачи скрыты, страница подборки отвечает 404 и исчезает из навигации и sitemap; публикация задачи вернёт её на заданное место. Slug навсегда закрепляется после первой публикации. Для снятия используйте isPublished=false; удаления через MCP нет. Действующие права ADMIN, scope, срок токена и блокировки проверяются сервером при каждой операции.

Чего MCP не умеет

MCP не публикует курс напрямую и не снимает курс с публикации, не удаляет контент, не меняет владельцев, команды, доступы или зачисления. Для одной явно выбранной задачи допускается отдельное включение или выключение индексации по условиям выше. Он не работает со списками пользователей и учащихся, их контактами и персональными покупками; не создаёт платежи, возвраты, выплаты, bundle/legacy-промокоды или партнёрские начисления; не банит аккаунты. Для course-промокодов доступен только отдельный bulk upsert/deactivate. Для рассылок агент может подготовить собственный DRAFT, выбрать встроенный consent-only сегмент и задать course filters/exclusions. Он не может просматривать или искать получателей, получать их PII или preview аудитории, делать test/send/schedule или вызывать worker/provider. Перед отправкой администратор заново проверяет аудиторию в UI и явно подтверждает send.

В allowlist нет произвольного HTTP, SQL, shell, Prisma/raw database, файловой системы или универсального action. Неизвестное имя инструмента отклоняется протоколом.

Полное авторское содержимое при чтении

latorn_get_course_content, latorn_create_step и latorn_update_step возвращают полный валидированный Step.block: правильные ответы, hidden tests, preCode, testCases, testSuites, полный авторский goProject с public files и hidden HTTP checks, devtools configuration, correctIds, outcome feedback и referenceAnswers. Это teacher-only authoring contract: нужны PAT scope, явная привязка токена к курсу и актуальное право content:write. Learner/public API использует отдельную безопасную сериализацию: public Go-файлы и открытые checks видны, а hidden HTTP specs заменяются безопасными placeholders. В MCP DTO по-прежнему нет происхождения из банка заданий и operational metadata вне самого Step.block.

Полный технический договор, ограничения аналитики и правила human confirmation находятся в docs/MCP_SERVER.md репозитория Latorn.