memo-api

MaiMemo オープン API

認証とベース

• ベース URL：https://open.maimemo.com/open/api/v1
• トークン：環境変数 $MAIMEMO_TOKEN — 以下のいずれかから取得します：
  • アプリ：墨墨背单词 → オープン API
  • Web：https://open.maimemo.com/open/api/v1/tokens/openapi を開いて MaiMemo アカウントにログインし、トークンをコピーして貼り付けるようユーザーに依頼したうえで、$MAIMEMO_TOKEN に設定します
• トークンの有効期限：Web から取得したトークンの有効期間は 7 日間です。API 呼び出しでトークンの期限切れまたは無効（認証エラーなど）が示された場合は、Web へのログイン、コピー、貼り付けの手順を繰り返し、$MAIMEMO_TOKEN を更新するようユーザーに伝えてください。
• 認証ヘッダー：Authorization: Bearer $MAIMEMO_TOKEN

curl -s -X ${METHOD} "${BASE}/${PATH}" \
  -H "Authorization: Bearer $MAIMEMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '${BODY}'

レート制限：20/10s、40/60s、2000/5h

主な概念

• voc_id の解決：ほとんどのエンドポイントで必要なのはスペルではなく voc_id です。GET /vocabulary?spelling=word または POST /vocabulary/query（一括で最大 1000 件）を使って解決します。
• 更新には POST を使用：更新エンドポイントでは PUT/PATCH ではなく POST /resource/{id} を使います。
• ステータス値：リソースではステータス列挙値（PUBLISHED、UNPUBLISHED、DELETED）を使用します。値はドメインによって異なります。
• タイムスタンプ：すべての時刻は ISO 8601 形式です。学習日のフィルターには北京時間（UTC+8）を使用します。

ドメインごとの参照先

タスク	参照ファイル
voc_id／スペルから id を検索	vocabulary-api.md
カスタム語義の CRUD	interpretations-api.md
暗記メモ（連想／語呂合わせ／派生語／語根／語源／定型表現／文法／比較など）の CRUD	notes-api.md
単語リスト／クラウドノートを管理	notepads-api.md
例文の CRUD	phrases-api.md
学習の進捗、記録、スケジュール	study-api.md

エンドポイントを呼び出す前に、対応する参照ファイルを読んで、正確なパラメーター、本文のスキーマ、curl の例を確認してください。

学習での使用シーン

学習関連のエンドポイントはすべて POST で、ベータ版です（自動同期を有効にする必要があります）。

今日の進捗

エンドポイント：POST /study/get_study_progress（空の本文） 返される値：finished（完了数）、total（目標数）、study_time（ミリ秒）

シーン	エンドポイント	主なパラメーター
今日の残り単語数	get_study_progress	total - finished を計算
今日の学習時間	get_study_progress	study_time（ミリ秒 → 分）

今日の単語

エンドポイント：POST /study/get_today_items

シーン	エンドポイント	主なパラメーター
今日忘れた単語	get_today_items	is_finished: true、first_response = "FORGET" で絞り込み
今日の新出単語	get_today_items	is_new: true
未完了の単語	get_today_items	is_finished: false
特定の単語の履歴	get_today_items	spellings: ["word"] または voc_ids: ["id"]

学習記録

エンドポイント：POST /study/query_study_records

シーン	エンドポイント	主なパラメーター
今後 N 日以内に学習期限を迎える単語	query_study_records	next_study_date.end: "YYYY-MM-DDT00:00:00+08:00"、as_count: true
学習計画の単語総数	query_study_records	as_count: true（フィルターなし）
よく忘れる単語（定着しにくい単語）	query_study_records	ページを順に取得し、tags = "STICKING" で絞り込み
よく定着している単語	query_study_records	ページを順に取得し、tags = "WELL_FAMILIAR" で絞り込み
すべての学習データをエクスポート	query_study_records	next_study_date の範囲をずらしながらページを取得し、limit: 1000 を指定

単語の追加

エンドポイント：POST /study/add_words

シーン	エンドポイント	主なパラメーター
学習計画に単語を追加	add_words	words: [{"id": "voc_id"}]、最大 1000 件
単語を追加して復習を繰り上げ	add_words	advance: true（すぐに復習も開始します。レベル制限はありません）

復習の繰り上げ

エンドポイント：POST /study/advance_study

シーン	エンドポイント	主なパラメーター
単語の復習を繰り上げてすぐに復習	advance_study	voc_ids: ["voc_id1", ...]、最大 1000 件
復習の繰り上げ機能を利用するにはレベル 10 以上が必要です

複数のドメインにまたがるワークフローのヒント

• 単語に覚えやすい工夫を追加する：Vocabulary（voc_idを取得）→ Notes（作成）
• 例文を追加する：Vocabulary（voc_idを取得）→ Phrases（作成）
• カスタムの定義を追加する：Vocabulary（voc_idを取得）→ Interpretations（作成）
• 学習データから単語リストを作成する：学習記録（クエリ）→ Notepads（スペルを指定して作成）
• 単語の詳細情報をすべて取得する：Vocabulary（voc_idを取得）→ Interpretations + Notes + Phrases（すべて一覧表示）