IVGraphV1 LLM API
API mit reinem Lesezugriff für LLM-Agenten, Automatisierungsskripte und Integrationen. Bietet Zugriff auf die Graphdaten eines Notion-Workspaces — Suche, Knotendetails, Seiteninhalte und Graph-Traversierung.
Überblick
| Eigenschaft | Wert |
|---|---|
| Basis-URL | /v1/graph/ |
| Authentifizierung | Service-Token (Authorization: Bearer ivg_*) |
| Format | JSON |
| Anfragelimits | 20 Anfragen/10s als kurzzeitiges Limit, 600 Anfragen/15min als Zeitfensterlimit |
| Selbstbeschreibende Spezifikation | GET /v1/ (keine Authentifizierung erforderlich) |
Gemeinsame Parameter
Alle Endpunkte erfordern workspace_id:
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| workspace_id | string (UUID) | ja | UUID des Notion-Workspaces. Muss in den erlaubten workspace_ids des Tokens enthalten sein. |
Endpunkte
GET /v1/graph/search/
Suche im gesamten Workspace nach Knoten anhand ihres Titels. Nutzt Elasticsearch, sofern verfügbar, andernfalls erfolgt der Abgleich im Arbeitsspeicher.
Berechtigungsbereich: graph:search
Parameter:
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| q | string | ja | — | Suchanfrage (max. 256 Zeichen) |
| workspace_id | string | ja | — | UUID des Ziel-Workspaces |
| limit | int | nein | 20 | Ergebnisse pro Seite (max. 50) |
| type | string | nein | all | Filter: page, database oder user |
Beispielanfrage:
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();
Antwort:
{
"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}
]
}
Fehler:
| Status | Bedeutung |
|---|---|
| 400 | q oder workspace_id fehlt, Suchanfrage zu lang oder unzulässige Zeichen |
| 401 | Service-Token fehlt oder ist ungültig |
| 403 | Token verfügt nicht über den Berechtigungsbereich graph:search oder Workspace ist nicht in der Liste der erlaubten Workspaces enthalten |
| 404 | Keine synchronisierten Daten für diesen Workspace |
| 429 | Anfragelimit überschritten |
GET /v1/graph/nodes/{node_id}/
Rufe einen einzelnen Knoten mit allen unbedenklichen Feldern ab: Titel, Typ, URL, Symbol, Anzahl der Verbindungen, PageRank und Eigenschaften.
Berechtigungsbereich: graph:read
Parameter:
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| node_id | UUID | ja | Knoten-ID (im URL-Pfad) |
| workspace_id | string | ja | UUID des Ziel-Workspaces |
Beispielanfrage:
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();
Antwort:
{
"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": {}
}
}
Fehler:
| Status | Bedeutung |
|---|---|
| 400 | Ungültiges node_id-Format oder workspace_id fehlt |
| 401 | Service-Token fehlt oder ist ungültig |
| 403 | Token verfügt nicht über den Berechtigungsbereich graph:read oder Workspace ist nicht erlaubt |
| 404 | Knoten nicht gefunden oder keine synchronisierten Daten für den Workspace |
| 429 | Anfragelimit überschritten |
GET /v1/graph/content/{page_id}/
Rufe Seiteninhalte als Markdown und Klartext ab. Die Inhalte werden aus Notion-Blöcken extrahiert, die über Airbyte synchronisiert wurden.
Berechtigungsbereich: graph:read
Parameter:
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| page_id | UUID | ja | Seiten-ID (im URL-Pfad) |
| workspace_id | string | ja | UUID des Ziel-Workspaces |
Beispielanfrage:
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();
Antwort:
{
"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
}
Fehler:
| Status | Bedeutung |
|---|---|
| 400 | Ungültiges page_id-Format oder workspace_id fehlt |
| 401 | Service-Token fehlt oder ist ungültig |
| 403 | Token verfügt nicht über den Berechtigungsbereich graph:read oder Workspace ist nicht erlaubt |
| 404 | Seite nicht gefunden oder keine synchronisierten Daten für den Workspace |
| 429 | Anfragelimit überschritten |
GET /v1/graph/neighbors/{node_id}/
BFS-Traversierung, die Nachbarknoten und Kanten bis zu einer angegebenen Tiefe zurückgibt. Hilfreich, um die lokale Graphstruktur rund um einen Knoten zu erkunden.
Berechtigungsbereich: graph:neighbors
Parameter:
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| node_id | UUID | ja | — | ID des Startknotens (im URL-Pfad) |
| workspace_id | string | ja | — | UUID des Ziel-Workspaces |
| depth | int | nein | 1 | Traversierungstiefe (max. 3) |
| limit | int | nein | 20 | Maximale Anzahl zurückgegebener Nachbarknoten (max. 50) |
| direction | string | nein | both | Kantenrichtung: in, out oder both |
Beispielanfrage:
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();
Antwort:
{
"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"}
]
}
Fehler:
| Status | Bedeutung |
|---|---|
| 400 | Ungültiges node_id-Format oder workspace_id fehlt |
| 401 | Service-Token fehlt oder ist ungültig |
| 403 | Token verfügt nicht über den Berechtigungsbereich graph:neighbors oder Workspace ist nicht erlaubt |
| 404 | Knoten nicht gefunden oder keine synchronisierten Daten für den Workspace |
| 429 | Anfragelimit überschritten |
POST /v1/graph/traverse/
Finde mit BFS den kürzesten Pfad zwischen zwei Knoten. Gibt den Pfad als geordnete Liste von Knoten zurück oder null, wenn innerhalb der maximalen Tiefe kein Pfad existiert.
Berechtigungsbereich: graph:neighbors
Anfrageinhalt (JSON):
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| start_id | UUID | ja | — | Startknoten |
| target_id | UUID | ja | — | Zielknoten |
| workspace_id | string | ja | — | UUID des Ziel-Workspaces |
| max_depth | int | nein | 3 | Maximale Traversierungstiefe (max. 3) |
Beispielanfrage:
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();
Antwort (Pfad gefunden):
{
"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"}
]
}
Antwort (kein Pfad):
{
"start": "550e8400-e29b-41d4-a716-446655440001",
"target": "550e8400-e29b-41d4-a716-446655440099",
"path_length": null,
"path": []
}
Fehler:
| Status | Bedeutung |
|---|---|
| 400 | start_id/target_id/workspace_id fehlt oder ist ungültig |
| 401 | Service-Token fehlt oder ist ungültig |
| 403 | Token verfügt nicht über den Berechtigungsbereich graph:neighbors oder Workspace ist nicht erlaubt |
| 404 | Start- oder Zielknoten nicht gefunden oder keine synchronisierten Daten |
| 429 | Anfragelimit überschritten |
Selbstbeschreibende Spezifikation
GET /v1/ gibt die vollständige API-Spezifikation als JSON zurück. Keine Authentifizierung erforderlich.
curl "https://ivgraph.com/v1/"
Die Antwort enthält maschinenlesbares JSON mit allen Endpunkten, Parametern, Antwortschemas, Anfragelimits und Berechtigungsbereichen. Hilfreich für LLM-Agenten, um die API programmatisch zu erschließen.