# IVGraph API

> IVGraph visualizes your Notion workspace as an interactive 3D graph.
> Connect Notion, sync your data, explore relationships between pages, databases, and users.

## Authentication

- User API: JWT via Notion OAuth (`Authorization: Bearer <jwt>`)
- LLM/Agent API: Service token (`Authorization: Bearer ivg_<token>`)
- Create tokens: POST /api/tokens/ (max 10, scopes required)
- Scopes: graph:search, graph:read, graph:neighbors

## V1 LLM API (read-only)

Base: /v1/graph/
Auth: Service token (Bearer ivg_*)
Rate limits: 20 req/10s burst, 600 req/15min

- GET /v1/graph/search/ — Search nodes by title across a workspace. Uses Elasticsearch when available, falls back to in-memory matching.
- GET /v1/graph/nodes/{node_id}/ — Get a single node with all safe fields: title, type, URL, icon, connection counts, pagerank, and properties.
- GET /v1/graph/content/{page_id}/ — Get page content as markdown and plain text. Content is extracted from Notion blocks synced via Airbyte.
- 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.
- 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.
- GET /v1/ — API specification as JSON (no auth)

## Graph API

- GET /api/notion-graph/ — Full graph (nodes + edges + metadata + stats). JWT auth. ?demo=true for demo mode.

## Search API

- GET /api/search/?q= — Full-text search (BM25). JWT auth.
- GET /api/search/suggest/?q= — Autocomplete (min 2 chars). JWT auth.
- GET /api/search/semantic/?q= — Vector similarity search. JWT auth.
- GET /api/search/hybrid/?q= — BM25 + vector combined. JWT auth.
- GET /api/search/similar/<node_id>/ — Find similar nodes. JWT auth.
- GET /api/search/content/<page_id>/ — Page markdown content. JWT auth.

## Public Endpoints (no auth)

- GET /api/stats/public/ — Platform stats (users, nodes, syncs). Cached 24h.
- GET /api/health/ — Health check

## Links

- [Full API docs for LLMs](https://ivgraph.com/llms-full.txt)
- [Developer documentation](https://ivgraph.com/docs/)
- [Website](https://ivgraph.com)