Referencia de la API

API V1 para LLM

API de solo lectura para agentes LLM, scripts de automatización e integraciones. Permite acceder a los datos del grafo del espacio de trabajo de Notion: búsquedas, detalles de nodos, contenido de páginas y recorridos del grafo.

Descripción general

Propiedad Valor
URL base /v1/graph/
Autenticación Token de servicio (Authorization: Bearer ivg_*)
Formato JSON
Límites de solicitudes 20 solicitudes por ráfaga de 10s, 600 solicitudes por ventana de 15min
Especificación autodescriptiva GET /v1/ (no requiere autenticación)

Parámetros comunes

Todos los puntos de conexión requieren workspace_id:

Parámetro Tipo Obligatorio Descripción
workspace_id string (UUID) sí UUID del espacio de trabajo de Notion. Debe estar entre los workspace_ids permitidos por el token.

Puntos de conexión

GET /v1/graph/search/

Busca nodos por título en todo un espacio de trabajo. Utiliza Elasticsearch si está disponible; de lo contrario, busca coincidencias en memoria.

Ámbito: graph:search

Parámetros:

Parámetro Tipo Obligatorio Valor predeterminado Descripción
q string sí — Consulta de búsqueda (máximo 256 caracteres)
workspace_id string sí — UUID del espacio de trabajo de destino
limit int no 20 Resultados por página (máximo 50)
type string no all Filtro: page, database o user

Ejemplo de solicitud:

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();

Respuesta:

{
  "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}
  ]
}

Errores:

Estado Significado
400 Falta q o workspace_id, la consulta es demasiado larga o contiene caracteres no permitidos
401 El token de servicio falta o no es válido
403 El token no tiene el ámbito graph:search o el espacio de trabajo no está en la lista de permitidos
404 No hay datos sincronizados para este espacio de trabajo
429 Se ha superado el límite de solicitudes

GET /v1/graph/nodes/{node_id}/

Obtén un único nodo con todos los campos seguros: título, tipo, URL, icono, recuentos de conexiones, pagerank y propiedades.

Ámbito: graph:read

Parámetros:

Parámetro Tipo Obligatorio Descripción
node_id UUID sí ID del nodo (en la ruta de la URL)
workspace_id string sí UUID del espacio de trabajo de destino

Ejemplo de solicitud:

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();

Respuesta:

{
  "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": {}
  }
}

Errores:

Estado Significado
400 El formato de node_id no es válido o falta workspace_id
401 El token de servicio falta o no es válido
403 El token no tiene el ámbito graph:read o el espacio de trabajo no está permitido
404 No se ha encontrado el nodo o no hay datos sincronizados para el espacio de trabajo
429 Se ha superado el límite de solicitudes

GET /v1/graph/content/{page_id}/

Obtén el contenido de una página en Markdown y texto sin formato. El contenido se extrae de los bloques de Notion sincronizados mediante Airbyte.

Ámbito: graph:read

Parámetros:

Parámetro Tipo Obligatorio Descripción
page_id UUID sí ID de la página (en la ruta de la URL)
workspace_id string sí UUID del espacio de trabajo de destino

Ejemplo de solicitud:

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();

Respuesta:

{
  "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
}

Errores:

Estado Significado
400 El formato de page_id no es válido o falta workspace_id
401 El token de servicio falta o no es válido
403 El token no tiene el ámbito graph:read o el espacio de trabajo no está permitido
404 No se ha encontrado la página o no hay datos sincronizados para el espacio de trabajo
429 Se ha superado el límite de solicitudes

GET /v1/graph/neighbors/{node_id}/

Recorrido BFS que devuelve los vecinos y las aristas hasta una profundidad determinada. Es útil para explorar la estructura local del grafo alrededor de un nodo.

Ámbito: graph:neighbors

Parámetros:

Parámetro Tipo Obligatorio Valor predeterminado Descripción
node_id UUID sí — ID del nodo inicial (en la ruta de la URL)
workspace_id string sí — UUID del espacio de trabajo de destino
depth int no 1 Profundidad del recorrido (máximo 3)
limit int no 20 Número máximo de vecinos que se devuelven (máximo 50)
direction string no both Dirección de las aristas: in, out o both

Ejemplo de solicitud:

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();

Respuesta:

{
  "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"}
  ]
}

Errores:

Estado Significado
400 El formato de node_id no es válido o falta workspace_id
401 El token de servicio falta o no es válido
403 El token no tiene el ámbito graph:neighbors o el espacio de trabajo no está permitido
404 No se ha encontrado el nodo o no hay datos sincronizados para el espacio de trabajo
429 Se ha superado el límite de solicitudes

POST /v1/graph/traverse/

Encuentra el camino más corto entre dos nodos mediante BFS. Devuelve el camino como una lista ordenada de nodos, o null si no existe ningún camino dentro de la profundidad máxima.

Ámbito: graph:neighbors

Cuerpo de la solicitud (JSON):

Parámetro Tipo Obligatorio Valor predeterminado Descripción
start_id UUID sí — Nodo inicial
target_id UUID sí — Nodo de destino
workspace_id string sí — UUID del espacio de trabajo de destino
max_depth int no 3 Profundidad máxima del recorrido (máximo 3)

Ejemplo de solicitud:

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();

Respuesta (camino encontrado):

{
  "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"}
  ]
}

Respuesta (sin camino):

{
  "start": "550e8400-e29b-41d4-a716-446655440001",
  "target": "550e8400-e29b-41d4-a716-446655440099",
  "path_length": null,
  "path": []
}

Errores:

Estado Significado
400 Falta start_id/target_id/workspace_id o su valor no es válido
401 El token de servicio falta o no es válido
403 El token no tiene el ámbito graph:neighbors o el espacio de trabajo no está permitido
404 No se ha encontrado el nodo inicial o de destino, o no hay datos sincronizados
429 Se ha superado el límite de solicitudes

Especificación autodescriptiva

GET /v1/ devuelve la especificación completa de la API en formato JSON. No requiere autenticación.

curl "https://ivgraph.com/v1/"

Devuelve un JSON legible por máquinas con todos los puntos de conexión, parámetros, esquemas de respuesta, límites de solicitudes y ámbitos. Es útil para que los agentes LLM descubran la API de forma programática.