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: 墨墨背单词 → 开放 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 | 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)