Anota ヘルプ（API）

概要

Anota のノートとフォルダは、API キーを使って AI エージェントや外部のスクリプトから読み書きできます。使い方は 2 通りあります。

種類	エンドポイント	向いている使い方
REST API	`https://api.anota.info/v1`	スクリプト、HTTP を直接呼べる AI エージェント
MCP	`https://api.anota.info/mcp`	Claude などの MCP に対応した AI ツール

OpenAPI 3.1 のスキーマは https://api.anota.info/openapi.json にあります（認証は不要です）。

要求と応答の本文は JSON（UTF-8）です。日時は ISO 8601 形式の文字列で返ります。

認証

API キーはマイアカウント画面の「API キー」で発行します。発行したキーは、あとからでも一覧の「表示」でもう一度表示・コピーできます。キーと一緒に、接続先と AI エージェントへの依頼文も表示されます。

すべての要求に、次のヘッダーを付けます。

Authorization: Bearer anota_xxxxxxxx

キーには使い先（個人またはチーム）が含まれているので、ほかに付けるものはありません。
URL のクエリにキーを入れる形（?api_key= など）は受け付けません。
失効したキー、有効期限の切れたキーは 401 になります。

スコープ

スコープ	できること
`read`	GET の要求（ノートやフォルダの読み取り、検索）
`write`	POST・PUT・DELETE の要求（作成・更新・削除）

書き込みだけのキーでは読み取りができません。ふつうは両方を付けて発行してください。スコープが足りないと 403 forbidden になります。

API キーで使える範囲

API キーで読み書きできるのは、「API キーからのアクセスを許可する」が ON のフォルダのノートだけです。この設定は、すべてのノートに対して、またはフォルダごとに、アプリの画面で切り替えます（API からは変えられません）。

許可していないフォルダのノートを ID で指定すると 403 api_key_access_disabled になります。
一覧と検索の結果からは、許可していないフォルダのノートが黙って除かれます。そのため、1 ページ分の件数が limit より少なくなることがあります。
API キーで作ったフォルダは、最初から許可された状態になります。

このほか、ノートやフォルダの公開範囲（自分だけ・メンバー）は、アプリで使うときと同じように適用されます。チームで IP アドレスの制限をしている場合は、API にも適用されます（違反は 403 ip_restricted）。

ノート

メソッドとパス	内容
`GET /v1/pages`	ノートの一覧
`POST /v1/pages`	ノートを作る
`GET /v1/pages/{id}`	ノートを 1 件読む（本文を含む）
`PUT /v1/pages/{id}`	ノートを更新する
`DELETE /v1/pages/{id}`	ノートをゴミ箱に入れる
`POST /v1/pages/{id}/move`	ノートを別のフォルダへ移す
`GET /v1/pages/{id}/tags`	ノートのタグを読む
`PUT /v1/pages/{id}/tags`	ノートのタグを置き換える
`GET /v1/pages/{id}/backlinks`	このノートへリンクしているノート
`GET /v1/pages/{id}/versions`	版の履歴
`POST /v1/pages/{id}/comments`	コメントを付ける（チーム版）

ノートのデータ

ノートを返す API は、次の項目を持つオブジェクトを返します（値の無い項目は省かれることがあります）。

項目	内容
`page_id`	ノートの ID
`title` / `body`	タイトルと本文（Markdown）
`folder_id` / `folder_name`	入っているフォルダ
`tags`	タグ（カンマ区切りの文字列）
`permission`	`private`（自分だけ）または `member`（フォルダの設定に従う）
`version`	版の番号。更新するたびに増える
`deleted`	ゴミ箱に入っていれば `true`
`user_id` / `user_name`	作った人
`created_at` / `updated_at`	作成日時と更新日時

GET /v1/pages

クエリ: folder_id（フォルダで絞る）、offset（既定 0）、limit（既定 50、最大 100）。

{"pages": [ {ノート}, ... ], "offset": 0, "limit": 50}

総件数は返りません。返った件数が 0 になるまで offset を進めてください。

POST /v1/pages

{
  "title": "会議メモ",          // 必須
  "body": "# 議題\n- ...",     // Markdown
  "folder_id": "…",            // 省略すると既定のフォルダ
  "permission": "member",      // "private" で自分だけ
  "tags": ["meeting", "2026"]  // 配列またはカンマ区切りの文字列
}

作ったノートを 201 で返します。無料プランのノート数の上限に達していると 403 page_limit_reached です。

PUT /v1/pages/{id}

変えたい項目だけを送ります。title と body は、空にすると今の値のままになります。folder_id を送ると、そのフォルダへ移します。

version を付けると、その版から誰も更新していないときだけ更新します（食い違うと 409 version_conflict）。上書きを防ぐため、読み取ったときの version を付けることをおすすめします。

{"body": "# 議題\n- 更新しました", "version": 3}

DELETE /v1/pages/{id}

ノートをゴミ箱に入れ、{"success": true} を返します。完全に消すことはできません（アプリのゴミ箱から消します）。ゴミ箱のノートは更新できません（409 page_in_trash）。

その他

POST /v1/pages/{id}/move: 本文 {"folder_id": "…"}。
GET /v1/pages/{id}/tags: {"page_id": "…", "tags": ["…"]}。PUT は本文 {"tags": [...]} でタグをまるごと置き換えます（64 個まで、1 つ 128 バイトまで）。
GET /v1/pages/{id}/backlinks: {"page_id": "…", "backlinks": [{"page_id": "…", "title": "…"}]}。
GET /v1/pages/{id}/versions: {"page_id": "…", "versions": [{"version", "user_name", "created_at", "change_type", ...}]}。
POST /v1/pages/{id}/comments: 本文 {"body": "…", "thread_id": "…"}（thread_id はスレッドへの返信のときだけ）。

検索・タグ

GET /v1/search?q=キーワード: タイトルと本文の先頭から探し、{"pages": [...], "query": "…"} を返します（最大 50 件）。
GET /v1/tags: 使われているタグの一覧 {"tags": ["…"]}。

フォルダ

メソッドとパス	内容
`GET /v1/folders`	フォルダの一覧 `{"folders": [...]}`
`POST /v1/folders`	フォルダを作る。本文 `{"name": "…", "description": "…", "permission": "private"}`
`GET /v1/folders/{id}`	フォルダを 1 件。`?include_pages=true` で中のノートも返す
`PUT /v1/folders/{id}`	名前・説明・公開範囲を変える
`DELETE /v1/folders/{id}`	フォルダを消す。中のノートは `?move_pages_to=` のフォルダ（省略時は既定のフォルダ）へ移す

フォルダの主な項目: folder_id、name、description、permission、is_default、page_count、created_at、updated_at。

フォルダの作成・変更・削除は管理者だけができます（個人でお使いの場合はご本人が管理者です）。同じ名前のフォルダは作れません（409 conflict）。既定のフォルダは消せません。

エラー

エラーのときは、HTTP のステータスと次の形の本文を返します。

{"error": {"code": "version_conflict", "message": "…"}}

ステータス	code	主な原因
400	`invalid_request`	必須の項目が無い、存在しないフォルダを指定した
401	`unauthorized`	キーが無い・違う・失効した・期限切れ
403	`forbidden`	スコープや権限が足りない
403	`api_key_access_disabled`	API キーからのアクセスを許可していないフォルダ
403	`page_limit_reached`	無料プランのノート数の上限
403	`ip_restricted`	許可されていない IP アドレス
404	`not_found`	ノート・フォルダ・パスが無い
409	`version_conflict`	ほかの更新と食い違った。読み直してから更新する
409	`page_in_trash`	ゴミ箱のノートを更新・削除しようとした
500	`internal_error`	サーバーの問題。時間をおいて再試行する

MCP

MCP（Model Context Protocol）に対応した AI ツールからは、https://api.anota.info/mcp を MCP サーバーとして登録して使えます。通信は Streamable HTTP（JSON-RPC 2.0 を POST で 1 件ずつ送る形）で、認証は REST と同じく Authorization: Bearer ヘッダーの API キーです。

ツール	内容	主な引数
`search_notes`	キーワードでノートを探す	`query`
`get_note`	ノートを本文ごと読む	`page_id`
`list_folders`	フォルダの一覧	なし
`create_note`	ノートを作る	`title`、`body`、`folder_id`
`update_note`	ノートを更新する（本文はまるごと置き換え）	`page_id`、`title`、`body`
`add_comment`	コメントを付ける（チーム版）	`page_id`、`body`

Claude Code の場合の登録例:

claude mcp add --transport http anota https://api.anota.info/mcp --header "Authorization: Bearer anota_xxxxxxxx"

使える範囲（スコープ・フォルダの許可）は REST と同じです。

例

ノートの一覧を読む:

curl "https://api.anota.info/v1/pages?limit=20" \
  -H "Authorization: Bearer anota_xxxxxxxx"

ノートを作る:

curl -X POST https://api.anota.info/v1/pages \
  -H "Authorization: Bearer anota_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "今日のメモ", "body": "# メモ\n- 牛乳を買う"}'

読み取った版を付けて更新する:

curl -X PUT https://api.anota.info/v1/pages/PAGE_ID \
  -H "Authorization: Bearer anota_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"body": "# メモ\n- 牛乳を買った", "version": 1}'