memo-api

MaiMemo Open API

Auth & Base

• Base URL: https://open.maimemo.com/open/api/v1
• Token: env var $MAIMEMO_TOKEN — obtain it from either:
  • App: MaiMemo → Open 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 (association/homophone/derivation/root/etymology/collocation/grammar/contrast 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 (auto-sync needs to be enabled).

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)