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

Внешнее API (v1)

CRUD для слов и правил · обновлено 13 сентября 2026

Внешнее API позволяет сервисам читать и изменять данные пользователя Memo Dict: слова с прогрессом изучения, словари и правила (CRUD для слов и правил). Токен создаётся в приложении: Настройки → Аккаунт → API-токен. Базовый адрес API — https://learn.memo-dict.app (https://learn.memo-dict.app).

Аутентификация

Токен имеет формат mk_… и показывается один раз — сохраните его сразу. Перевыпуск токена в настройках отзывает предыдущий. Токен передаётся в заголовке:

Authorization: Bearer mk_v1StGXR8_Z5jdHi6B-myT

Коды ошибок

Формат ошибки: { "error": "Описание" }.

GET /api/v1/words

Пагинационный список слов пользователя с информацией об изучении, сортировкой и фильтрами.

Сортировка

• createdAt — дата добавления слова.
• temperature — уровень знания по stability FSRS (без карточки — cold).
• due — срок следующего повторения; слова без карточки идут в конце при asc.
• accuracy — точность ответов в % (correctCount/reviewCount; без карточки 0%).
• random — случайный порядок. С seed порядок стабилен между страницами; без seed сервер генерирует свой и возвращает его в поле seed ответа — передавайте его при листании.

Примеры запросов

curl -H "Authorization: Bearer mk_..." \
  'https://learn.memo-dict.app/api/v1/words?dictionaryId=d_xyz789&limit=2'

curl -H "Authorization: Bearer mk_..." \
  'https://learn.memo-dict.app/api/v1/words?due=overdue&sort=due&order=asc'

Пример ответа

{
  "data": [
    {
      "id": "w_abc123",
      "dictionaryId": "d_xyz789",
      "sourceText": "hello",
      "targetText": "привет",
      "pronunciation": "[həˈloʊ]",
      "inLearningPool": true,
      "learningScore": 3,
      "learningCompletedAt": null,
      "temperature": "warm",
      "reps": 5,
      "correctCount": 4,
      "incorrectCount": 1,
      "lapses": 1,
      "createdAt": 1710000000000,
      "updatedAt": 1710005000000
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 42,
  "totalPages": 21
}

Поля изучения

• inLearningPool — слово в текущей группе изучения.
• learningScore — накопленные баллы (0–5+), ≥ 5 — изучено.
• reps, correctCount, incorrectCount, lapses — счётчики карточки повторения (FSRS); у слова без карточки все нули.
• temperature — уровень знания по stability FSRS (см. таблицу ниже); cold у слов без карточки.

Температура слова

POST /api/v1/check-words

Проверка наличия слов в словаре: текст токенизируется, каждый токен сравнивается со словами словаря — сначала точное совпадение по нормализованной форме (регистр и пунктуация не учитываются), затем векторное сравнение нераспознанных токенов (до 3 кандидатов со схожестью > 75%). POST используется, так как текст передаётся в теле запроса. Чужой или несуществующий словарь → 404.

curl -X POST -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"dictionaryId": "d_xyz789", "text": "Hello wrold!"}' \
  'https://learn.memo-dict.app/api/v1/check-words'

{
  "results": [
    {
      "token": "Hello",
      "exact": true,
      "matches": [
        {
          "wordId": "w_abc123",
          "sourceText": "hello",
          "learning": { "learned": true, "learningScore": 5, "temperature": "warm" }
        }
      ]
    },
    {
      "token": "wrold",
      "exact": false,
      "matches": [
        {
          "wordId": "w_def456",
          "sourceText": "world",
          "similarity": 0.87,
          "learning": { "learned": false, "learningScore": 0, "temperature": "cold" }
        }
      ]
    }
  ],
  "fuzzyAvailable": true
}

fuzzyAvailable: false — векторное сравнение недоступно, вернулись только точные совпадения. similarity приходит только у fuzzy-совпадений. Поле learning показывает изученность слова словаря: learned — слово пройдено в Learning v2 (≥ 5 баллов), learningScore — накопленные баллы, temperature — уровень знания (cold, если слово не повторялось). Так можно отличить «слово выучено» от «слово просто есть в словаре».

GET /api/v1/dictionaries

Список словарей пользователя (без удалённых), по возрастанию порядка.

curl -H "Authorization: Bearer mk_..." \
  'https://learn.memo-dict.app/api/v1/dictionaries'

{
  "data": [
    {
      "id": "d_xyz789",
      "sourceLang": "en",
      "targetLang": "ru",
      "createdAt": 1710000000000,
      "updatedAt": 1710000000000
    }
  ],
  "total": 1
}

GET /api/v1/rules

Пагинационный список правил пользователя с сортировкой.

curl -H "Authorization: Bearer mk_..." \
  'https://learn.memo-dict.app/api/v1/rules?page=1&limit=20&sort=createdAt&order=asc'

{
  "data": [
    {
      "id": "n_001",
      "title": "Präteritum",
      "contentMarkdown": "# Präteritum\n...",
      "categoryIds": [],
      "createdAt": 1710000000000,
      "updatedAt": 1710000000000
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}

GET /api/v1/rules/search

Семантический поиск по правилам пользователя: возвращает ближайшие к запросу правила по смыслу (векторное сравнение, модель google/gemini-embedding-2). Ищутся только готовые правила.

В каждом результате — поле score (похожесть 0–1): > 0.6 — уверенное совпадение; 0.5–0.6 — возможен фоновый шум. Порог отсечки не применяется — топ возвращается всегда. Если векторный движок недоступен, вернётся пустой data.

curl -H "Authorization: Bearer mk_..." \
  'https://learn.memo-dict.app/api/v1/rules/search?query=прошедшее+время&limit=3'

{
  "data": [
    {
      "id": "n_001",
      "title": "Прошедшее время в корейском",
      "contentMarkdown": "## Кратко\n...",
      "categoryIds": [],
      "createdAt": 1710000000000,
      "updatedAt": 1710000000000,
      "score": 0.72
    }
  ],
  "total": 1,
  "query": "прошедшее время"
}

POST /api/v1/words

Создание слова в словаре пользователя. Прогресс изучения не задаётся: новые слова создаются «холодными» (без карточки, score 0). Чужой или удалённый словарь → 404.

curl -X POST -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"dictionaryId": "d_xyz789", "sourceText": "hello", "targetText": "привет"}' \
  'https://learn.memo-dict.app/api/v1/words'

Ответ — созданное слово (как в списке GET /words, HTTP 201).

GET / PATCH / DELETE /api/v1/words/:id

• GET — одно слово с информацией об изучении (404, если не найдено/чужое).
• PATCH — частичное обновление: передайте только изменяемые поля (sourceText, targetText, pronunciation, notes, examples, tagIds, а также dictionaryId для переноса в другой свой словарь). Прогресс изучения через API не меняется. Ответ — обновлённое слово.
• DELETE — мягкое удаление: слово пропадает из списков и удаляется на всех устройствах пользователя при синхронизации. Ответ: { "ok": true }.

curl -X PATCH -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"targetText": "привет!"}' \
  'https://learn.memo-dict.app/api/v1/words/w_abc123'

POST /api/v1/rules

Создание правила (заметки с kind=rule).

curl -X POST -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Präteritum", "contentMarkdown": "# Präteritum\n..."}' \
  'https://learn.memo-dict.app/api/v1/rules'

Ответ — созданное правило (как в списке GET /rules, HTTP 201).

GET / PATCH / DELETE /api/v1/rules/:id

• GET — одно правило (404, если не найдено/чужое).
• PATCH — частичное обновление: title, contentMarkdown, categoryIds. Ответ — обновлённое правило.
• DELETE — мягкое удаление правила. Ответ: { "ok": true }.

Все изменения (создание, обновление, удаление) синхронизируются на устройства пользователя автоматически.