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

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

Task	Read reference file
Look up voc_id / spelling → id	vocabulary-api.md
CRUD custom definitions	interpretations-api.md
CRUD mnemonics (联想/谐音/派生/词根/词源/固搭/语法/对比 etc.)	notes-api.md
Manage word lists / cloud notepads	notepads-api.md
CRUD example sentences	phrases-api.md
Study progress, records, schedules	study-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)

Scene	Endpoint	Key params
Words left today	get_study_progress	compute total - finished
Study time today	get_study_progress	study_time (ms → min)

Today's Words

Endpoint: POST /study/get_today_items

Scene	Endpoint	Key params
Forgotten words today	get_today_items	is_finished: true, filter first_response = "FORGET"
New words today	get_today_items	is_new: true
Unfinished words	get_today_items	is_finished: false
Specific word history	get_today_items	spellings: ["word"] or voc_ids: ["id"]

Study Records

Endpoint: POST /study/query_study_records

Scene	Endpoint	Key params
Words due in next N days	query_study_records	next_study_date.end: "YYYY-MM-DDT00:00:00+08:00", as_count: true
Total words in plan	query_study_records	as_count: true (no filters)
Frequently forgotten (sticky)	query_study_records	iterate pages, filter tags = "STICKING"
Well-familiar words	query_study_records	iterate pages, filter tags = "WELL_FAMILIAR"
Export all study data	query_study_records	paginate via sliding next_study_date window, limit: 1000

Adding Words

Endpoint: POST /study/add_words

Scene	Endpoint	Key params
Add words to plan	add_words	words: [{"id": "voc_id"}], max 1000
Add and advance review	add_words	advance: true (also triggers immediate review, no level limit)

Advance Review

Endpoint: POST /study/advance_study

Scene	Endpoint	Key params
Advance words for immediate review	advance_study	voc_ids: ["voc_id1", ...], max 1000
Requires 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)