MaiMemo Open API
Auth & Base
- - Base URL: INLINECODE0
- Token: env var
$MAIMEMO_TOKEN — set via app (墨墨背单词 → 开放 API) - Auth header: INLINECODE2
CODEBLOCK0
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 | INLINECODE10 |
| 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 | INLINECODE20 | compute INLINECODE21 |
| 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 | INLINECODE25 | INLINECODE26 , filter INLINECODE27 |
| 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 | INLINECODE36 | INLINECODE37 , INLINECODE38 |
| 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 | INLINECODE49 | INLINECODE50 , 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 | INLINECODE54 | INLINECODE55 , max 1000 |
| Requires level 10+ to unlock advance review feature |
| |
Multi-domain Workflow Hints
- - Add mnemonic to word: Vocabulary (get vocid) → Notes (create)
- Add example sentence: Vocabulary (get vocid) → Phrases (create)
- Add custom definition: Vocabulary (get vocid) → Interpretations (create)
- Build word list from study data: Study records (query) → Notepads (create with spellings)
- Full word info: Vocabulary (get vocid) → Interpretations + Notes + Phrases (list all)
MaiMemo Open API
认证与基础
- - 基础URL: https://open.maimemo.com/open/api/v1
- 令牌: 环境变量 $MAIMEMOTOKEN — 通过应用设置（墨墨背单词 → 开放 API）
- 认证头: Authorization: Bearer $MAIMEMOTOKEN
bash
curl -s -X ${METHOD} ${BASE}/${PATH} \
-H Authorization: Bearer $MAIMEMO_TOKEN \
-H Content-Type: application/json \
-d ${BODY}
速率限制: 20次/10秒, 40次/60秒, 2000次/5小时
核心概念
- - vocid 解析: 大多数接口需要 vocid，而非拼写。通过 GET /vocabulary?spelling=word 或 POST /vocabulary/query（批量最多1000个）解析。
- 使用POST进行更新: 更新接口使用 POST /resource/{id}，而非 PUT/PATCH。
- 状态值: 资源使用状态枚举（PUBLISHED、UNPUBLISHED、DELETED）— 因领域而异。
- 时间戳: 所有时间均为 ISO 8601 格式。学习日期筛选使用北京时间（UTC+8）。
领域路由
| 任务 | 参考文件 |
|---|
| 查找 voc_id / 拼写 → id | vocabulary-api.md |
| 自定义释义的增删改查 |
interpretations-api.md |
| 助记的增删改查（联想/谐音/派生/词根/词源/固定搭配/语法/对比等） | notes-api.md |
| 管理单词列表/云笔记本 | notepads-api.md |
| 例句的增删改查 | phrases-api.md |
| 学习进度、记录、计划 | study-api.md |
在调用任何接口之前，请阅读相应的参考文件以获取准确的参数、请求体结构和 curl 示例。
学习使用场景
所有学习接口均为 POST 且为 测试版（需要打开自动同步）。
今日进度
接口: POST /study/get
studyprogress（空请求体）
返回: finished（已完成数量）、total（目标数量）、study_time（毫秒）
| 场景 | 接口 | 关键参数 |
|---|
| 今日剩余单词 | getstudyprogress | 计算 total - finished |
| 今日学习时长 |
get
studyprogress | study_time（毫秒 → 分钟） |
今日单词
接口: POST /study/get
todayitems
| 场景 | 接口 | 关键参数 |
|---|
| 今日遗忘的单词 | gettodayitems | isfinished: true，筛选 firstresponse = FORGET |
| 今日新词 |
get
todayitems | is_new: true |
| 未完成的单词 | get
todayitems | is_finished: false |
| 特定单词历史 | get
todayitems | spellings: [word] 或 voc_ids: [id] |
学习记录
接口: POST /study/query
studyrecords
| 场景 | 接口 | 关键参数 |
|---|
| 未来N天到期的单词 | querystudyrecords | nextstudydate.end: YYYY-MM-DDT00:00:00+08:00，ascount: true |
| 计划中总单词数 |
querystudy
records | ascount: true（无筛选条件） |
| 频繁遗忘（顽固）单词 | query
studyrecords | 分页遍历，筛选 tags = STICKING |
| 非常熟悉的单词 | query
studyrecords | 分页遍历，筛选 tags = WELL_FAMILIAR |
| 导出所有学习数据 | query
studyrecords | 通过滑动 next
studydate 窗口分页，limit: 1000 |
添加单词
接口: POST /study/add_words
| 场景 | 接口 | 关键参数 |
|---|
| 向计划添加单词 | addwords | words: [{id: vocid}]，最多1000个 |
| 添加并提前复习 |
add_words | advance: true（同时触发即时复习，无等级限制） |
提前复习
接口: POST /study/advance_study
| 场景 | 接口 | 关键参数 |
|---|
| 提前单词进行即时复习 | advancestudy | vocids: [voc_id1, ...]，最多1000个 |
| 需要等级10+才能解锁提前复习功能 |
| |
多领域工作流提示
- - 为单词添加助记: 词汇（获取 vocid）→ 笔记（创建）
- 添加例句: 词汇（获取 vocid）→ 短语（创建）
- 添加自定义释义: 词汇（获取 vocid）→ 释义（创建）
- 从学习数据构建单词列表: 学习记录（查询）→ 笔记本（使用拼写创建）
- 完整单词信息: 词汇（获取 vocid）→ 释义 + 笔记 + 短语（列出全部）
