IVGraphV1 LLM API
LLMエージェント、自動化スクリプト、インテグレーション向けの読み取り専用APIです。Notionワークスペースのグラフデータにアクセスし、検索、ノード詳細の取得、ページ内容の取得、グラフの探索を行えます。
概要
| プロパティ | 値 |
|---|---|
| ベースURL | /v1/graph/ |
| 認証 | サービストークン（Authorization: Bearer ivg_*） |
| 形式 | JSON |
| レート制限 | バースト時は10秒あたり20リクエスト、15分の時間枠内で600リクエスト |
| 自己記述型の仕様 | GET /v1/（認証不要） |
共通パラメータ
すべてのエンドポイントでworkspace_idが必須です。
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_id | string (UUID) | はい | NotionワークスペースのUUIDです。トークンで許可されたworkspace_idsに含まれている必要があります。 |
エンドポイント
GET /v1/graph/search/
ワークスペース全体のノードをタイトルで検索します。Elasticsearchが利用可能な場合はそれを使用し、利用できない場合はメモリ内での照合に切り替えます。
スコープ： graph:search
パラメータ：
| パラメータ | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| q | string | はい | — | 検索クエリ（最大256文字） |
| workspace_id | string | はい | — | 対象ワークスペースのUUID |
| limit | int | いいえ | 20 | 1ページあたりの結果数（最大50） |
| type | string | いいえ | all | 絞り込み：page、database、またはuser |
リクエスト例：
curl -H "Authorization: Bearer ivg_your_token" \
"https://ivgraph.com/v1/graph/search?q=project&workspace_id=abc-123&limit=5"
import requests
resp = requests.get(
"https://ivgraph.com/v1/graph/search",
headers={"Authorization": "Bearer ivg_your_token"},
params={"q": "project", "workspace_id": "abc-123", "limit": 5}
)
data = resp.json()
const resp = await fetch(
"https://ivgraph.com/v1/graph/search?q=project&workspace_id=abc-123&limit=5",
{ headers: { Authorization: "Bearer ivg_your_token" } }
);
const data = await resp.json();
レスポンス：
{
"query": "project",
"total": 3,
"results": [
{"id": "550e8400-e29b-41d4-a716-446655440001", "type": "page", "title": "Project Alpha", "score": 0.95},
{"id": "550e8400-e29b-41d4-a716-446655440002", "type": "database", "title": "Projects Tracker", "score": 0.72},
{"id": "550e8400-e29b-41d4-a716-446655440003", "type": "page", "title": "Project Notes", "score": 0.61}
]
}
エラー：
| ステータス | 意味 |
|---|---|
| 400 | qまたはworkspace_idが未指定、クエリが長すぎる、または許可されていない文字が含まれています |
| 401 | サービストークンが未指定または無効です |
| 403 | トークンにgraph:searchスコープがないか、ワークスペースが許可リストに含まれていません |
| 404 | このワークスペースの同期済みデータがありません |
| 429 | レート制限を超えています |
GET /v1/graph/nodes/{node_id}/
単一のノードについて、安全に公開できるすべてのフィールドを取得します。タイトル、種類、URL、アイコン、接続数、ページランク、プロパティが含まれます。
スコープ： graph:read
パラメータ：
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| node_id | UUID | はい | ノードID（URLパス内） |
| workspace_id | string | はい | 対象ワークスペースのUUID |
リクエスト例：
curl -H "Authorization: Bearer ivg_your_token" \
"https://ivgraph.com/v1/graph/nodes/550e8400-e29b-41d4-a716-446655440001/?workspace_id=abc-123"
import requests
node_id = "550e8400-e29b-41d4-a716-446655440001"
resp = requests.get(
f"https://ivgraph.com/v1/graph/nodes/{node_id}/",
headers={"Authorization": "Bearer ivg_your_token"},
params={"workspace_id": "abc-123"}
)
node = resp.json()["node"]
const nodeId = "550e8400-e29b-41d4-a716-446655440001";
const resp = await fetch(
`https://ivgraph.com/v1/graph/nodes/${nodeId}/?workspace_id=abc-123`,
{ headers: { Authorization: "Bearer ivg_your_token" } }
);
const { node } = await resp.json();
レスポンス：
{
"node": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"type": "page",
"title": "Project Alpha",
"url": "https://www.notion.so/Project-Alpha-550e8400e29b41d4a716446655440001",
"icon": {"type": "emoji", "emoji": "\ud83d\ude80"},
"connections_in": 5,
"connections_out": 12,
"connections_total": 17,
"pagerank": 0.42,
"properties": {}
}
}
エラー：
| ステータス | 意味 |
|---|---|
| 400 | node_idの形式が無効か、workspace_idが未指定です |
| 401 | サービストークンが未指定または無効です |
| 403 | トークンにgraph:readスコープがないか、ワークスペースが許可されていません |
| 404 | ノードが見つからないか、ワークスペースの同期済みデータがありません |
| 429 | レート制限を超えています |
GET /v1/graph/content/{page_id}/
ページの内容をMarkdownとプレーンテキストで取得します。内容は、Airbyte経由で同期されたNotionブロックから抽出されます。
スコープ： graph:read
パラメータ：
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| page_id | UUID | はい | ページID（URLパス内） |
| workspace_id | string | はい | 対象ワークスペースのUUID |
リクエスト例：
curl -H "Authorization: Bearer ivg_your_token" \
"https://ivgraph.com/v1/graph/content/550e8400-e29b-41d4-a716-446655440001/?workspace_id=abc-123"
import requests
page_id = "550e8400-e29b-41d4-a716-446655440001"
resp = requests.get(
f"https://ivgraph.com/v1/graph/content/{page_id}/",
headers={"Authorization": "Bearer ivg_your_token"},
params={"workspace_id": "abc-123"}
)
content = resp.json()
print(content["markdown"])
const pageId = "550e8400-e29b-41d4-a716-446655440001";
const resp = await fetch(
`https://ivgraph.com/v1/graph/content/${pageId}/?workspace_id=abc-123`,
{ headers: { Authorization: "Bearer ivg_your_token" } }
);
const { markdown, plain_text } = await resp.json();
レスポンス：
{
"page_id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Project Alpha",
"markdown": "# Project Alpha\n\nThis is the main project page.\n\n## Goals\n\n- Launch beta by Q2\n- Reach 100 users",
"plain_text": "Project Alpha\nThis is the main project page.\nGoals\nLaunch beta by Q2\nReach 100 users",
"has_content": true
}
エラー：
| ステータス | 意味 |
|---|---|
| 400 | page_idの形式が無効か、workspace_idが未指定です |
| 401 | サービストークンが未指定または無効です |
| 403 | トークンにgraph:readスコープがないか、ワークスペースが許可されていません |
| 404 | ページが見つからないか、ワークスペースの同期済みデータがありません |
| 429 | レート制限を超えています |
GET /v1/graph/neighbors/{node_id}/
幅優先探索（BFS）で指定した深さまで探索し、近傍ノードとエッジを返します。ノード周辺の局所的なグラフ構造を調べるのに役立ちます。
スコープ： graph:neighbors
パラメータ：
| パラメータ | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| node_id | UUID | はい | — | 開始ノードのID（URLパス内） |
| workspace_id | string | はい | — | 対象ワークスペースのUUID |
| depth | int | いいえ | 1 | 探索の深さ（最大3） |
| limit | int | いいえ | 20 | 返す近傍ノード数の上限（最大50） |
| direction | string | いいえ | both | エッジの方向：in、out、またはboth |
リクエスト例：
curl -H "Authorization: Bearer ivg_your_token" \
"https://ivgraph.com/v1/graph/neighbors/550e8400-e29b-41d4-a716-446655440001/?workspace_id=abc-123&depth=2&limit=10"
import requests
node_id = "550e8400-e29b-41d4-a716-446655440001"
resp = requests.get(
f"https://ivgraph.com/v1/graph/neighbors/{node_id}/",
headers={"Authorization": "Bearer ivg_your_token"},
params={"workspace_id": "abc-123", "depth": 2, "limit": 10}
)
data = resp.json()
print(f"Found {data['total']} neighbors")
const nodeId = "550e8400-e29b-41d4-a716-446655440001";
const resp = await fetch(
`https://ivgraph.com/v1/graph/neighbors/${nodeId}/?workspace_id=abc-123&depth=2&limit=10`,
{ headers: { Authorization: "Bearer ivg_your_token" } }
);
const { neighbors, edges, total } = await resp.json();
レスポンス：
{
"node_id": "550e8400-e29b-41d4-a716-446655440001",
"depth": 2,
"total": 4,
"neighbors": [
{"id": "550e8400-e29b-41d4-a716-446655440010", "type": "page", "title": "Sprint Planning"},
{"id": "550e8400-e29b-41d4-a716-446655440011", "type": "database", "title": "Tasks"},
{"id": "550e8400-e29b-41d4-a716-446655440012", "type": "page", "title": "Design Doc"},
{"id": "550e8400-e29b-41d4-a716-446655440013", "type": "user", "title": "Alice"}
],
"edges": [
{"source": "550e8400-e29b-41d4-a716-446655440001", "target": "550e8400-e29b-41d4-a716-446655440010", "type": "reference"},
{"source": "550e8400-e29b-41d4-a716-446655440001", "target": "550e8400-e29b-41d4-a716-446655440011", "type": "parent"},
{"source": "550e8400-e29b-41d4-a716-446655440010", "target": "550e8400-e29b-41d4-a716-446655440012", "type": "mention"},
{"source": "550e8400-e29b-41d4-a716-446655440012", "target": "550e8400-e29b-41d4-a716-446655440013", "type": "mention"}
]
}
エラー：
| ステータス | 意味 |
|---|---|
| 400 | node_idの形式が無効か、workspace_idが未指定です |
| 401 | サービストークンが未指定または無効です |
| 403 | トークンにgraph:neighborsスコープがないか、ワークスペースが許可されていません |
| 404 | ノードが見つからないか、ワークスペースの同期済みデータがありません |
| 429 | レート制限を超えています |
POST /v1/graph/traverse/
BFSを使って2つのノード間の最短経路を探します。経路をノードの順序付きリストとして返します。探索の最大深さ以内に経路が存在しない場合はnullを返します。
スコープ： graph:neighbors
リクエスト本文（JSON）：
| パラメータ | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| start_id | UUID | はい | — | 開始ノード |
| target_id | UUID | はい | — | 目的ノード |
| workspace_id | string | はい | — | 対象ワークスペースのUUID |
| max_depth | int | いいえ | 3 | 探索の最大深さ（最大3） |
リクエスト例：
curl -X POST "https://ivgraph.com/v1/graph/traverse/" \
-H "Authorization: Bearer ivg_your_token" \
-H "Content-Type: application/json" \
-d '{
"start_id": "550e8400-e29b-41d4-a716-446655440001",
"target_id": "550e8400-e29b-41d4-a716-446655440012",
"workspace_id": "abc-123"
}'
import requests
resp = requests.post(
"https://ivgraph.com/v1/graph/traverse/",
headers={
"Authorization": "Bearer ivg_your_token",
"Content-Type": "application/json"
},
json={
"start_id": "550e8400-e29b-41d4-a716-446655440001",
"target_id": "550e8400-e29b-41d4-a716-446655440012",
"workspace_id": "abc-123"
}
)
path = resp.json()["path"]
const resp = await fetch("https://ivgraph.com/v1/graph/traverse/", {
method: "POST",
headers: {
Authorization: "Bearer ivg_your_token",
"Content-Type": "application/json"
},
body: JSON.stringify({
start_id: "550e8400-e29b-41d4-a716-446655440001",
target_id: "550e8400-e29b-41d4-a716-446655440012",
workspace_id: "abc-123"
})
});
const { path, path_length } = await resp.json();
レスポンス（経路が見つかった場合）：
{
"start": "550e8400-e29b-41d4-a716-446655440001",
"target": "550e8400-e29b-41d4-a716-446655440012",
"path_length": 2,
"path": [
{"id": "550e8400-e29b-41d4-a716-446655440001", "type": "page", "title": "Project Alpha"},
{"id": "550e8400-e29b-41d4-a716-446655440010", "type": "page", "title": "Sprint Planning"},
{"id": "550e8400-e29b-41d4-a716-446655440012", "type": "page", "title": "Design Doc"}
]
}
レスポンス（経路がない場合）：
{
"start": "550e8400-e29b-41d4-a716-446655440001",
"target": "550e8400-e29b-41d4-a716-446655440099",
"path_length": null,
"path": []
}
エラー：
| ステータス | 意味 |
|---|---|
| 400 | start_id/target_id/workspace_idが未指定または無効です |
| 401 | サービストークンが未指定または無効です |
| 403 | トークンにgraph:neighborsスコープがないか、ワークスペースが許可されていません |
| 404 | 開始ノードまたは目的ノードが見つからないか、同期済みデータがありません |
| 429 | レート制限を超えています |
自己記述型の仕様
GET /v1/は、API仕様全体をJSONで返します。認証は不要です。
curl "https://ivgraph.com/v1/"
すべてのエンドポイント、パラメータ、レスポンススキーマ、レート制限、スコープを含む、機械可読なJSONを返します。LLMエージェントがプログラムからAPIの仕様を把握するのに役立ちます。