API overview

The VOL REST API is versioned under /v1. All bodies are JSON (Content-Type: application/json) except the binary graph files and the SSE chat stream.

Base URL

Environment	Base URL
Hosted (Cloudflare Pages)	https://<your-vol-host>/api/v1
Self-hosted, direct	http://localhost:8010/v1
Local app dev (Vite proxy)	/api/v1 → http://localhost:8010/v1

The SDK takes the base without /v1 (baseUrl: "https://<host>/api") and appends it.

Authentication

Send X-API-Key: vol_live_… (integrations) or Authorization: Bearer <supabase access token> (signed-in users). Public endpoints: GET /v1/health, GET /v1/cases, POST /v1/docs/ask. See Authentication.

Endpoints

Method	Path	Group
GET	/v1/health	Health
GET	/v1/cases	Cases
POST	/v1/chat	Chat
POST	/v1/search	Search
GET	/v1/graph/{case}/meta	Graph
GET	/v1/graph/{case}/positions.bin	Graph
GET	/v1/graph/{case}/links.bin	Graph
GET	/v1/graph/{case}/labels.json	Graph
GET	/v1/graph/{case}/clusters.json	Graph
GET	/v1/graph/{case}/nodes/{nodeIndex}	Graph
GET	/v1/graph/{case}/neighbors/{nodeIndex}	Graph
POST	/v1/graph/{case}/subgraph	Graph
GET	/v1/clusters/{case}/{clusterId}	Clusters
GET	/v1/me	Account & API keys
GET	/v1/keys	Account & API keys
POST	/v1/keys	Account & API keys
DELETE	/v1/keys/{id}	Account & API keys
POST	/v1/docs/ask	Docs assistant

Additional endpoints (from OpenAPI, not yet in the contract)

Method	Path
DELETE	/v1/keys/{key_id}

The live OpenAPI schema is also served by vol-api at /docs (Swagger UI) and /openapi.json.

Errors

Errors use a single envelope; see Errors.

{ "error": { "code": "node_not_found", "message": "Node 99999 does not exist" } }