Read-only API for LLM agents, automation scripts, and integrations. Provides access to Notion workspace graph data — search, node details, page content, and graph traversal.
Overview
| Property | Value |
|---|---|
| Base URL | /v1/graph/ |
| Authentication | Service Token (Authorization: Bearer ivg_*) |
| Format | JSON |
| Rate Limits | 20 req/10s burst, 600 req/15min window |
| Self-describing spec | GET /v1/ (no auth required) |
Common Parameters
All endpoints require workspace_id:
| Param | Type | Required | Description |
|---|---|---|---|
| workspace_id | string (UUID) | yes | Notion workspace UUID. Must be in token's allowed workspace_ids. |
Endpoints
GET /v1/graph/search/
Search nodes by title across a workspace. Uses Elasticsearch when available, falls back to in-memory matching.
Scope: graph:search
Parameters:
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| q | string | yes | — | Search query (max 256 chars) |
| workspace_id | string | yes | — | Target workspace UUID |
| limit | int | no | 20 | Results per page (max 50) |
| type | string | no | all | Filter: page, database, or user |
Example request:
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();
Response:
{
"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}
]
}
Errors:
| Status | Meaning |
|---|---|
| 400 | Missing q or workspace_id, query too long, or disallowed characters |
| 401 | Missing or invalid service token |
| 403 | Token lacks graph:search scope or workspace not in allowed list |
| 404 | No synced data for this workspace |
| 429 | Rate limit exceeded |
GET /v1/graph/nodes/{node_id}/
Get a single node with all safe fields: title, type, URL, icon, connection counts, pagerank, and properties.
Scope: graph:read
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
| node_id | UUID | yes | Node ID (in URL path) |
| workspace_id | string | yes | Target workspace UUID |
Example request:
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();
Response:
{
"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": {}
}
}
Errors:
| Status | Meaning |
|---|---|
| 400 | Invalid node_id format or missing workspace_id |
| 401 | Missing or invalid service token |
| 403 | Token lacks graph:read scope or workspace not allowed |
| 404 | Node not found or no synced data for workspace |
| 429 | Rate limit exceeded |
GET /v1/graph/content/{page_id}/
Get page content as markdown and plain text. Content is extracted from Notion blocks synced via Airbyte.
Scope: graph:read
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
| page_id | UUID | yes | Page ID (in URL path) |
| workspace_id | string | yes | Target workspace UUID |
Example request:
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();
Response:
{
"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
}
Errors:
| Status | Meaning |
|---|---|
| 400 | Invalid page_id format or missing workspace_id |
| 401 | Missing or invalid service token |
| 403 | Token lacks graph:read scope or workspace not allowed |
| 404 | Page not found or no synced data for workspace |
| 429 | Rate limit exceeded |
GET /v1/graph/neighbors/{node_id}/
BFS traversal returning neighbors and edges up to a given depth. Useful for exploring local graph structure around a node.
Scope: graph:neighbors
Parameters:
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| node_id | UUID | yes | — | Starting node ID (in URL path) |
| workspace_id | string | yes | — | Target workspace UUID |
| depth | int | no | 1 | Traversal depth (max 3) |
| limit | int | no | 20 | Max neighbors to return (max 50) |
| direction | string | no | both | Edge direction: in, out, or both |
Example request:
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();
Response:
{
"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"}
]
}
Errors:
| Status | Meaning |
|---|---|
| 400 | Invalid node_id format or missing workspace_id |
| 401 | Missing or invalid service token |
| 403 | Token lacks graph:neighbors scope or workspace not allowed |
| 404 | Node not found or no synced data for workspace |
| 429 | Rate limit exceeded |
POST /v1/graph/traverse/
Find the shortest path between two nodes using BFS. Returns the path as an ordered list of nodes, or null if no path exists within the max depth.
Scope: graph:neighbors
Request body (JSON):
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| start_id | UUID | yes | — | Starting node |
| target_id | UUID | yes | — | Target node |
| workspace_id | string | yes | — | Target workspace UUID |
| max_depth | int | no | 3 | Max traversal depth (max 3) |
Example request:
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();
Response (path found):
{
"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"}
]
}
Response (no path):
{
"start": "550e8400-e29b-41d4-a716-446655440001",
"target": "550e8400-e29b-41d4-a716-446655440099",
"path_length": null,
"path": []
}
Errors:
| Status | Meaning |
|---|---|
| 400 | Missing or invalid start_id/target_id/workspace_id |
| 401 | Missing or invalid service token |
| 403 | Token lacks graph:neighbors scope or workspace not allowed |
| 404 | Start or target node not found, or no synced data |
| 429 | Rate limit exceeded |
Self-Describing Spec
GET /v1/ returns the full API specification as JSON. No authentication required.
curl "https://ivgraph.com/v1/"
This returns machine-readable JSON with all endpoints, parameters, response schemas, rate limits, and scopes. Useful for LLM agents to discover the API programmatically.