MaiMemo Open API#

Auth & Base#

• Base URL: https://open.maimemo.com/open/api/v1

• Token: env var $MAIMEMO_TOKEN — obtain it from either:

  • App: 墨墨背单词 → 开放 API
  • Web: open https://open.maimemo.com/open/api/v1/tokens/openapi, log in to the MaiMemo account, ask the user to copy the Token and paste it back, then set it as $MAIMEMO_TOKEN

• Token expiry: Tokens from the web source are valid for 7 days. If an API call indicates the token is expired/invalid (for example auth failure), tell the user to repeat the web login/copy/paste flow and update $MAIMEMO_TOKEN.

• Auth header: Authorization: Bearer $MAIMEMO_TOKEN

bash

curl -s -X ${METHOD} "${BASE}/${PATH}" \
  -H "Authorization: Bearer $MAIMEMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '${BODY}'

Rate limits: 20/10s, 40/60s, 2000/5h

Key Concepts#

• voc_id resolution: Most endpoints need voc_id, not spelling. Resolve via GET /vocabulary?spelling=word or POST /vocabulary/query (batch up to 1000).
• POST for updates: Update endpoints use POST /resource/{id}, not PUT/PATCH.
• Status values: Resources use status enums ( PUBLISHED, UNPUBLISHED, DELETED) — vary by domain.
• Timestamps: All times are ISO 8601. Study date filters use Beijing timezone (UTC+8).

Domain Routing#

TaskRead reference fileLook up voc_id / spelling → idvocabulary-api.mdCRUD custom definitionsinterpretations-api.mdCRUD mnemonics (联想/谐音/派生/词根/词源/固搭/语法/对比 etc.)notes-api.mdManage word lists / cloud notepadsnotepads-api.mdCRUD example sentencesphrases-api.mdStudy progress, records, schedulesstudy-api.md

Before calling any endpoint, read the corresponding reference file for exact params, body schema, and curl examples.

Study Usage Scenes#

All study endpoints are POST and beta (需要打开自动同步).

Today's Progress#

Endpoint: POST /study/get_study_progress (empty body) Returns: finished (done count), total (target count), study_time (ms)

SceneEndpointKey paramsWords left todayget_study_progresscompute total - finishedStudy time todayget_study_progress``study_time (ms → min)

Today's Words#

Endpoint: POST /study/get_today_items

SceneEndpointKey paramsForgotten words todayget_today_items``is_finished: true, filter first_response = "FORGET"New words todayget_today_items``is_new: trueUnfinished wordsget_today_items``is_finished: falseSpecific word historyget_today_items``spellings: ["word"] or voc_ids: ["id"]

Study Records#

Endpoint: POST /study/query_study_records

SceneEndpointKey paramsWords due in next N daysquery_study_records``next_study_date.end: "YYYY-MM-DDT00:00:00+08:00", as_count: trueTotal words in planquery_study_records``as_count: true (no filters)Frequently forgotten (sticky)query_study_recordsiterate pages, filter tags = "STICKING"Well-familiar wordsquery_study_recordsiterate pages, filter tags = "WELL_FAMILIAR"Export all study dataquery_study_recordspaginate via sliding next_study_date window, limit: 1000

Adding Words#

Endpoint: POST /study/add_words

SceneEndpointKey paramsAdd words to planadd_words``words: [{"id": "voc_id"}], max 1000Add and advance reviewadd_words``advance: true (also triggers immediate review, no level limit)

Advance Review#

Endpoint: POST /study/advance_study

SceneEndpointKey paramsAdvance words for immediate reviewadvance_study``voc_ids: ["voc_id1", ...], max 1000Requires level 10+ to unlock advance review feature

Multi-domain Workflow Hints#

• Add mnemonic to word: Vocabulary (get voc_id) → Notes (create)
• Add example sentence: Vocabulary (get voc_id) → Phrases (create)
• Add custom definition: Vocabulary (get voc_id) → Interpretations (create)
• Build word list from study data: Study records (query) → Notepads (create with spellings)
• Full word info: Vocabulary (get voc_id) → Interpretations + Notes + Phrases (list all)