Справочник API
Статьи и редакции
Произвольные статьи с изображениями, таблицами, кодом, SEO и связями с курсами. Агент готовит черновик, публикацией управляет администратор.
Маршруты раздела
| Метод | Маршрут | Доступ | Назначение |
|---|---|---|---|
GET |
/api/articles/analytics |
Администратор или PAT с ARTICLE_ANALYTICS_READ | Вклад статей: from/to (ISO, до 90 дней), articleId/courseId, offset/limit до 100. Переходы, регистрации, обучение и подтверждённые покупки; только агрегаты. |
GET |
/api/articles |
Администратор или PAT с ARTICLES_WRITE | Список статей: q, offset и limit до 100; текущая и опубликованная версии. |
GET |
/api/articles/[id] |
Администратор или PAT с ARTICLES_WRITE | Текст, SEO, связанные курсы и история редакций. version читает конкретную редакцию. |
PUT |
/api/articles |
Администратор или PAT с ARTICLES_WRITE | Создать или обновить полный черновик. Для обновления обязательны id и expectedVersion. |
POST |
/api/articles/[id]/restore |
Администратор или PAT с ARTICLES_WRITE | Восстановить revisionVersion в новый черновик с expectedVersion. |
GET |
/api/articles/courses |
Администратор или PAT с ARTICLES_WRITE | Найти связанные курсы по названию; q, offset, limit. |
POST |
/api/uploads/article-media |
Администратор или PAT с ARTICLES_WRITE | Загрузить изображение multipart-полем file и получить URL для HTML. PNG, JPEG, WebP до 8 МБ; SVG до 2 МБ становится PNG. |
Эффективность статей
Отдельное необязательное право ARTICLE_ANALYTICS_READ (только live ADMIN, без course binding) открывает GET /api/articles/analytics и MCP latorn_get_article_analytics. Выберите один режим периода: days=1|30|90 по часам сервера и календарю МСК; включительные даты fromDate/toDate (YYYY-MM-DD, до 90 дней); либо прежние ISO from/to с часовым поясом и исключающим концом. Для сегодняшнего дня сервер сам ограничивает конец текущим временем; будущие даты отклоняются. Необязательны articleId, courseId, offset, limit до 100. sort=views|transitions|registrations|learningStarts|purchases и direction=desc|asc сортируют весь каталог до пагинации; по умолчанию views desc, равные значения — id asc. period и sorting фиксируют применённые границы/порядок, totals устраняет дубли курсов внутри статьи. observedSince — первое сохранившееся наблюдение, не полная история или дата запуска сбора; отсутствие наблюдений не доказывает отсутствие поисковых кликов.
В ответе — статья, просмотры по уникальным браузерным journeys и строки курсов: переходы, регистрации, начало обучения по подтверждённому учебному действию, подтверждённые покупки. Когорта по первому переходу в периоде, конверсии в следующие 30 дней; mature показывает, закончилось ли окно. Этапы независимы, несколько статей могут помочь одной покупке, поэтому суммы статей не являются общими продажами. Первоначальный источник и источник входа в статью разделены. Unknown не означает органику. Без analytics allow связей нет, прошлое не восстанавливается, людей и отдельные платежи API/MCP не возвращает. ARTICLES_WRITE само этот отчёт не открывает.
Доступ и публикация
Администратор выдаёт отдельное необязательное право ARTICLES_WRITE; привязка к курсам для него не нужна. На каждом вызове проверяются действующий токен, актуальная роль администратора и отсутствие блокировки. Это право не открывает пользователей, оплаты, уроки или скрытые проверки.
API и MCP сохраняют черновик. Опубликованная редакция на сайте не изменяется, пока человек не нажмёт «Опубликовать изменения» в админке. Опубликовать или снять статью с публикации через PAT/MCP нельзя. Предпросмотр доступен вошедшему администратору по previewPath из ответа; публичный URL — /articles/[slug].
Полное состояние черновика
{
"slug": "numpy-arrays",
"title": "Массивы NumPy: практический разбор",
"seoTitle": "Массивы NumPy — руководство с примерами",
"seoDescription": "Разбираем форму, типы данных и операции над массивами NumPy на практических примерах.",
"content": "<h2>Форма массива</h2><p>Объяснение и примеры.</p>",
"courseIds": ["course-id"]
}
content — HTML до 500 000 символов: изображения, таблицы, код и математические формулы общего редактора Latorn. Максимум 20 уникальных связанных курсов. courseIds создаёт взаимные ссылки в разделах связанных материалов; содержательную ссылку в нужном месте текста добавляйте отдельно, например <a href="/courses/numpy-course">Практика работы с массивами</a>.
Для обновления добавьте id и expectedVersion из последнего чтения. Конфликт отвечает 409 ARTICLE_CHANGED и не затирает чужую правку. Адрес закрепляется после первой публикации. История неизменна; восстановление создаёт новую версию, не удаляет прошлые и не публикуется автоматически.
MCP-инструменты
latorn_list_articles— список с фильтрами и версиями.latorn_get_article— текущее состояние либо конкретнаяversion.latorn_save_article— полное сохранение черновика.latorn_restore_article—id,expectedVersion,revisionVersion.latorn_list_article_courses— найти ID и адрес курса для связи и ссылки.
Изображения загружаются обычным REST multipart-запросом; полученный URL вставляется в HTML. MCP не скачивает произвольные внешние адреса и не предоставляет файловую систему. Публикация, снятие с публикации и удаление через MCP недоступны.
