notion

Notion

Notion には 2 つの方法で接続できます。どちらも同じインテグレーショントークンを使います。利用可能な方法を選んでください。

◆ ntn CLI — Notion 公式の CLI です。構文が簡潔で、ファイルを 1 行でアップロードでき、Workers で必要です。2026 年 5 月時点では macOS と Linux のみ対応しています（Windows 対応は「近日公開予定」です）。インストール済みの場合はデフォルトです。 ◆ HTTP + curl — Windows を含む、あらゆる環境で動作します。ntn がインストールされていない場合のデフォルトのフォールバックです。

セットアップ

1. インテグレーショントークンを取得する（どちらの方法にも必要）

1. https://notion.so/my-integrations でインテグレーションを作成します
2. API キーをコピーします（ntn_ または secret_ で始まります）
3. ${HERMES_HOME:-~/.hermes}/.env に保存します：

   NOTION_API_KEY=ntn_your_key_here
   

4. Notion で対象のページ／データベースをインテグレーションと共有します。ページメニューの ... → Connect to → インテグレーション名を選択します。これを行わないと、ページが存在していても API はそのページに対して 404 を返します。

2. ntn をインストールする（macOS／Linux で推奨される方法）

# Recommended
curl -fsSL https://ntn.dev | bash

# Or via npm (needs Node 22+, npm 10+)
npm install --global ntn

ntn --version    # verify

ntn login は省略し、代わりにインテグレーショントークンを使用してください。 ブラウザーは不要で、ヘッドレス環境でも動作します：

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN
export NOTION_KEYRING=0                       # don't try to use the OS keychain

すべてのセッションで環境変数が引き継がれるよう、これらのエクスポートをシェルプロファイル（または ${HERMES_HOME:-~/.hermes}/.env）に追加してください。

3. 実行時に方法を選択する

if command -v ntn >/dev/null 2>&1; then
  # use ntn
else
  # fall back to curl
fi

Windows ユーザーは、ネイティブ版 ntn が提供されるまでステップ 2 を完全に省略してください。パス B で問題なく動作します。今すぐ CLI の使いやすさを利用したい場合は、WSL2 内に ntn をインストールしてください。

API の基本

すべての HTTP リクエストで Notion-Version: 2025-09-03 が必要です。ntn はこれを自動で処理します。このバージョンでは、ユーザーが「データベース」と呼ぶものは、API ではデータソースと呼ばれます。

パス A — ntn CLI（推奨、macOS／Linux）

Raw API リクエスト（curl の短縮形）

ntn api v1/users                                  # GET
# POST with inline body
ntn api v1/pages parent[page_id]=abc123 \
  properties[title][0][text][content]="Notes"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH; := is non-string (bool/num/null)

構文に関する注意：

• key=value — 文字列フィールド
• key[nested]=value — ネストされたオブジェクトのフィールド
• key:=value — 型付きの代入（ブール値、数値、null、配列）

検索

ntn api v1/search query="page title"

ページのメタデータを読み取る

ntn api v1/pages/{page_id}

ページを Markdown として読み取る（エージェント向け）

ntn api v1/pages/{page_id}/markdown

ページのコンテンツをブロックとして読み取る

ntn api v1/blocks/{page_id}/children

Markdown からページを作成する

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Notes from meeting" \
  markdown="# Agenda

- Q3 roadmap
- Hiring"

Markdown でページを更新する

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## Update

Shipped the prototype."

データベース（データソース）をクエリする

ntn api v1/data_sources/{data_source_id}/query -X POST \
  filter[property]=Status filter[select][equals]=Active

sorts、複数のフィルター句、または複合条件を含む複雑なクエリでは、JSON をパイプで渡します：

echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
  ntn api v1/data_sources/{data_source_id}/query -X POST --json -

ファイルのアップロード（1 行で実行 — CLI の最大の利点）

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

HTTP では 3 ステップ（アップロードの作成 → バイト列の PUT → 参照）となる方法と比べてください。

便利な環境変数

変数	効果
NOTION_API_TOKEN	認証トークン（キーチェーンより優先）— インテグレーショントークンを設定します
NOTION_KEYRING=0	OS のキーチェーンの代わりに、ファイルベースの認証情報を ~/.config/notion/auth.json に保存します
NOTION_WORKSPACE_ID	ワークスペース選択プロンプトを省略します

パス B — HTTP + curl（クロスプラットフォーム、Windows ではデフォルト）

すべてのリクエストで次の形式を使用します：

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Windows では、Windows 10 以降に同梱されている curl をそのまま使用できます。PowerShell ユーザーは Invoke-RestMethod も使用できます。

検索

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

ページのメタデータを読み取る

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

ページを Markdown として読み取る（エージェント向け）

ブロックの JSON よりもモデルに渡しやすい形式です。

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

ページのコンテンツをブロックとして読み取る（構造が必要な場合）

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Markdown からページを作成する

POST /v1/pages は markdown ボディパラメーターを受け付けます。

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "properties": {"title": [{"text": {"content": "Notes from meeting"}}]},
    "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday"
  }'

Markdown でページを更新する

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "## Update\n\nShipped the prototype."}'

データベース内にページを作成する（型付きプロパティ）

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

データベース（データソース）をクエリする

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

データベースを作成する

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

ページのプロパティを更新する

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

ページにブロックを追加する

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello from Hermes!"}}]}}
    ]
  }'

ファイルのアップロード（3 ステップの手順）

# 1. Create upload
curl -s -X POST "https://api.notion.com/v1/file_uploads" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.png", "content_type": "image/png"}'

# 2. PUT bytes to the upload_url returned above
curl -s -X PUT "{upload_url}" --data-binary @photo.png

# 3. Reference {file_upload_id} in a page/block payload

プロパティの型

データベース項目でよく使われるプロパティ形式：

• タイトル： {"title": [{"text": {"content": "..."}}]}
• リッチテキスト： {"rich_text": [{"text": {"content": "..."}}]}
• セレクト： {"select": {"name": "Option"}}
• マルチセレクト： {"multi_select": [{"name": "A"}, {"name": "B"}]}
• 日付： {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
• チェックボックス： {"checkbox": true}
• 数値： {"number": 42}
• URL： {"url": "https://..."}
• メールアドレス： {"email": "[email protected]"}
• リレーション： {"relation": [{"id": "page_id"}]}

API バージョン 2025-09-03 — データベースとデータソース

• データベースはデータソースになりました。 クエリと取得には /data_sources/ エンドポイントを使用してください。
• データベースごとに 2 つの ID があります： database_id と data_source_id。
  • ページを作成するときは database_id を使用します：parent: {"database_id": "..."}
  • クエリを実行するときは data_source_id を使用します：POST /v1/data_sources/{id}/query
• 検索では、データベースは data_source_id フィールドを含む "object": "data_source" として返されます。

Notion ワーカー（高度な機能、ntn が必要です）

ワーカーは、Notion がホストする TypeScript プログラムです。1 つのワーカーで、以下の任意の組み合わせを公開できます。

• 同期 — 外部 API から Notion データベースに、スケジュールに従ってデータを取り込みます（デフォルトは 30 分）。
• ツール — Notion のカスタムエージェント内で呼び出し可能なツールとして表示されます。
• Webhook — 外部サービス（GitHub、Stripe など）から HTTP イベントを受信し、Notion 上で処理します。

プラン／プラットフォームによる制限：

• CLI はすべてのプランで利用できます。ワーカーのデプロイには Business または Enterprise が必要です。
• 2026 年 5 月時点で、ntn は macOS/Linux 専用です。Windows ユーザーは WSL2 を使用するか、ネイティブ対応をお待ちください。
• 2026 年 8 月 11 日までは無料です。それ以降は Notion クレジットに基づく従量課金になります。

最小限のワーカー

ntn workers new my-worker      # scaffold
cd my-worker
# Edit src/index.ts
ntn workers deploy --name my-worker

src/index.ts：

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("greet", {
  title: "Greet a User",
  description: "Returns a friendly greeting",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `Hello, ${name}!`,
});

Webhook 機能

worker.webhook("onGithubPush", {
  title: "GitHub Push Handler",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody (for signature verification), event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

デプロイ後、ntn workers webhooks list を実行すると、Notion が生成した URL が表示されます。この URL は秘密情報として扱ってください。署名検証を追加しない限り、この URL を知っている人は誰でもイベントを POST できます。

ワーカーのライフサイクルコマンド

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # run a sync now
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # recent invocations
ntn workers runs logs <run-id>
ntn workers webhooks list

ワーカーの構築を依頼された場合は、ntn workers new でひな形を作成し、src/index.ts にコードを記述して、必要なシークレットを ntn workers env set で設定し、デプロイしてください。API の全機能については、Notion のドキュメント（https://developers.notion.com/workers）を参照してください。

Notion 独自の Markdown（/markdown エンドポイントで使用）

標準の CommonMark に、Notion 固有のブロックを表す XML 風のタグを加えたものです。インデントにはタブを使用してください。

CommonMark にないブロック：

<callout icon="🎯" color="blue_bg">
	Ship the MVP by **Friday**.
</callout>

<details color="gray">
<summary>Toggle title</summary>
	Children indented one tab
</details>

<columns>
	<column>Left side</column>
	<column>Right side</column>
</columns>

<table_of_contents color="gray"/>

インライン要素：

• メンション：<mention-user url="..."/>、<mention-page url="...">Title</mention-page>、<mention-date start="2026-05-15"/>
• 下線：<span underline="true">text</span>
• 色：<span color="blue">text</span> または 1 行目にブロックレベルの {color="blue"}
• 数式：インラインは $x^2$、ブロックは $$ ... $$
• 引用：[^https://example.com]

色： gray brown orange yellow green blue purple pink red と、背景用の *_bg バリエーションです。

見出しレベル 5／6 は H4 にまとめられます。複数行の > は個別の引用ブロックとして表示されます。複数行の引用には、1 つの > の中で <br> を使用してください。

適切な方法の選択

タスク	mac / Linux	Windows
ページの読み書き、検索、データベースへのクエリ	ntn api ...	curl
エージェントが要約するページの読み取り	ntn api v1/pages/{id}/markdown	curl /markdown エンドポイント
ファイルのアップロード	ntn files create < file	3 ステップの HTTP フロー
単発の API 調査	ntn api ...	curl
Notion がホストする同期／Webhook／エージェントツールの構築	ntn workers ...	WSL2 + ntn workers ...

注意事項

• ページ ID／データベース ID は UUID です（ハイフンの有無はどちらでも受け付けられます）。
• レート制限は、平均して約 3 リクエスト／秒です。CLI を使ってもこの制限は回避できません。
• API ではデータベースのビューフィルターを設定できません。設定できるのは UI のみです。
• データソースを作成してページに埋め込む場合は、"is_inline": true を使用してください。
• 進捗バーを抑制してエージェントの出力を整えるため、curl には必ず -s を指定してください。
• JSON を読み取るときは jq にパイプしてください：... | jq '.results[0].properties'。
• Notion は MCP サーバー（Notion MCP、データベース操作で以前のバージョンより約 91％トークン効率が向上）も提供しています。セッション内から Notion にストリーミングアクセスしたい場合は、Hermes の MCP サポート経由で接続してください。ただし、ほとんどの単発タスクでは上記の方法で十分です。