API для разработчиков

Content API позволяет заливать новости, кирпичики, конструкции, экспедиции и связи между ними прямо по HTTP — без гита и пересборки. Всё идемпотентно (upsert по slug): повторный запрос обновляет, а не дублирует.

Авторизация

Все запросы к /api/admin/* требуют секретный ключ в заголовке. Ключ лежит в ADMIN_API_KEY на сервере (посмотреть: grep ADMIN_API_KEY .env.production). Держи его в секрете — он даёт полный контроль над контентом.

Authorization: Bearer <ADMIN_API_KEY>
# или
x-api-key: <ADMIN_API_KEY>

Базовый адрес:

https://e-bricks.ru

Новости

Создать или обновить новость. Принимает объект или массив. Тело — markdown. Форматы: TEXT · VIDEO · GALLERY · LINK.

curl -X POST https://e-bricks.ru/api/admin/articles \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Запускаем неделю космоса",
    "excerpt": "Короткое описание для превью и поиска.",
    "format": "TEXT",
    "coverUrl": "https://.../cover.jpg",
    "body": "## Заголовок\n\nТекст в **markdown** со списками и [ссылками](/lab).",
    "tags": ["событие", "астрономия"],
    "status": "PUBLISHED"
  }'

slug можно не указывать — сгенерируется из заголовка. status: DRAFT (по умолчанию) или PUBLISHED.

Задания (кирпичики, конструкции, экспедиции)

Кирпичик — атом знания с проверкой (predict-reveal или quiz):

curl -X POST https://e-bricks.ru/api/admin/nodes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "slug": "bio-cell",
    "kind": "BRICK",
    "subject": "BIOLOGY",
    "title": "Клетка — кирпичик жизни",
    "summary": "Всё живое состоит из клеток.",
    "estMinutes": 10,
    "bodyMdx": "Короткое объяснение понятия…",
    "data": {
      "check": {
        "kind": "predict",
        "prompt": "Что общего у дерева, гриба и человека?",
        "options": ["Ничего", "Состоят из клеток", "Дышат жабрами"],
        "answer": 1,
        "reveal": "Все они состоят из клеток — базовой единицы жизни."
      }
    },
    "skills": [{ "skill": "MODELING" }, { "skill": "CRITICAL", "weight": 2 }]
  }'

Конструкция — постройка с 6-шаговым циклом исследователя и тренажёром:

{
  "slug": "bio-plant-build",
  "kind": "BUILD",
  "subject": "BIOLOGY",
  "title": "Прорасти семя",
  "trainerKey": "ph",
  "trainerParams": {},
  "data": {
    "cycle": {
      "wonder": "Что нужно семени, чтобы проснуться?",
      "hypothesisPrompt": "Предположи, какие условия важнее всего.",
      "plan": ["Замочить семена", "Разные условия", "Наблюдать 5 дней"],
      "actionHint": "Проведи опыт дома и внеси данные.",
      "reflectPrompts": ["Что подтвердилось?", "Что удивило?"],
      "sharePrompt": "Опиши, при каких условиях семена проросли."
    }
  },
  "skills": [{ "skill": "EXPERIMENT", "weight": 2 }]
}

quiz-проверка вместо predict:

"data": { "check": {
  "kind": "quiz",
  "question": "Где у растения идёт фотосинтез?",
  "options": [
    { "text": "В листьях", "correct": true, "why": "В хлоропластах листьев." },
    { "text": "В корнях", "correct": false, "why": "Корни всасывают воду, света там нет." }
  ]
}}

Уроки (композиция блоков)

Урок — узел с kind: "LESSON" и data.blocks — массивом разнотипных блоков. Так один урок совмещает несколько заданий и становится полным. Типы блоков: text · predict · quiz · numeric · rank · aiCatch · case · investigation.

{
  "slug": "lesson-water",
  "kind": "LESSON",
  "subject": "CHEMISTRY",
  "title": "Тайна воды",
  "data": { "blocks": [
    { "type": "text", "title": "Зачин", "body": "markdown-текст…" },
    { "type": "predict", "prompt": "Что произойдёт, если…",
      "options": ["A","B","C"], "answer": 1, "reveal": "объяснение механизма" },
    { "type": "numeric", "prompt": "Оцени, сколько…", "unit": "°C",
      "answer": 100, "tolerance": 0.15, "reveal": "…" },
    { "type": "rank", "prompt": "Расставь по порядку",
      "items": ["первый","второй","третий"], "reveal": "…" },
    { "type": "aiCatch", "prompt": "Найди ошибку ИИ",
      "claim": "правдоподобно неверное утверждение", "reveal": "в чём подвох" },
    { "type": "case", "intro": "загадочная ситуация",
      "clues": [{ "label": "Улика 1", "text": "…" }],
      "question": "Почему?", "options": [
        { "text": "верно", "correct": true, "why": "…" },
        { "text": "неверно", "correct": false, "why": "…" } ] },
    { "type": "investigation", "key": "pendulum", "intro": "поиграй с моделью" }
  ] },
  "skills": [{ "skill": "HYPOTHESIS", "weight": 2 }]
}

rank.items задаются в правильном порядке. investigation.key — из реестра лабораторий (сейчас: pendulum).

Связи (граф знаний)

Связывает узлы по slug. Типы: PREREQUISITE (нужно пройти до), RELATED, CROSS_SUBJECT (межпредметная стыковка), PART_OF (входит в экспедицию).

curl -X POST https://e-bricks.ru/api/admin/edges \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '[
    { "from": "bio-cell", "to": "bio-plant-build", "kind": "PREREQUISITE" },
    { "from": "bio-cell", "to": "chem-ph", "kind": "CROSS_SUBJECT" }
  ]'

Массовая заливка

Целый раздел одним запросом. Порядок гарантирован: сначала узлы, потом связи (можно ссылаться на только что созданные узлы), потом новости.

curl -X POST https://e-bricks.ru/api/admin/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "nodes": [ { "slug": "bio-cell", "kind": "BRICK", ... } ],
    "edges": [ { "from": "bio-cell", "to": "bio-dna", "kind": "RELATED" } ],
    "articles": [ { "title": "Добавили биологию!", "body": "...", "status": "PUBLISHED" } ]
  }'

Справочник значений