MaiMemo Open API

Auth & Base

• Base URL: https://open.maimemo.com/open/api/v1
• Token: env var $MAIMEMO_TOKEN — set via app (墨墨背单词 → 开放 API)
• 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

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)

Today's Words

Endpoint: POST /study/get_today_items

Study Records

Endpoint: POST /study/query_study_records

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)