Graph

Knowledge map artifacts and neighbourhood queries. See Graph data formats.

Method	Path
GET	`/api/v1/graph/{case}/meta`
GET	`/api/v1/graph/{case}/positions.bin`
GET	`/api/v1/graph/{case}/links.bin`
GET	`/api/v1/graph/{case}/labels.json`
GET	`/api/v1/graph/{case}/clusters.json`
GET	`/api/v1/graph/{case}/nodes/{nodeIndex}`
GET	`/api/v1/graph/{case}/neighbors/{nodeIndex}`
POST	`/api/v1/graph/{case}/subgraph`

Graph metadata

GET /api/v1/graph/{case}/meta

Counts, bounds and version of the knowledge map.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/meta" \
  -H "X-API-Key: $VOL_API_KEY"

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.meta("papers");

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/meta",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

{
  "case": "papers",
  "version": "ragflow_v2",
  "nodes": 7656,
  "links": 61248,
  "bounds": {
    "min": [
      -512.3,
      -498.1,
      -470.9
    ],
    "max": [
      506.7,
      515.2,
      489.4
    ]
  },
  "clusters": 42
}

Node positions

GET /api/v1/graph/{case}/positions.bin

Binary float32 little-endian x, y, z per node. See Graph data formats.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/positions.bin" \
  -H "X-API-Key: $VOL_API_KEY" \
  -o positions.bin

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
const positions = await vol.graph.positions("papers"); // Float32Array

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/positions.bin",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
data = r.content  # bytes; see the graph data formats guide

Response: application/octet-stream, cached with Cache-Control: public, max-age=86400, immutable and ETag.

Links

GET /api/v1/graph/{case}/links.bin

Binary int32 little-endian adjacency in ngraph format (source -(id+1), neighbours id+1).

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/links.bin" \
  -H "X-API-Key: $VOL_API_KEY" \
  -o links.bin

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
const links = await vol.graph.links("papers"); // Int32Array

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/links.bin",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
data = r.content  # bytes; see the graph data formats guide

Response: application/octet-stream, cached with Cache-Control: public, max-age=86400, immutable and ETag.

Labels

GET /api/v1/graph/{case}/labels.json

Title of every node, in nodeIndex order.

From the API schema: Array of node titles; index = nodeIndex.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/labels.json" \
  -H "X-API-Key: $VOL_API_KEY"

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.labels("papers");

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/labels.json",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

[
  "Graph-augmented retrieval for scientific QA",
  "RAPTOR: recursive abstractive processing",
  "…"
]

Map clusters

GET /api/v1/graph/{case}/clusters.json

Geometric clusters of the layout and the node → cluster assignment.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/clusters.json" \
  -H "X-API-Key: $VOL_API_KEY"

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.clusters("papers");

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/clusters.json",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

{
  "clusters": [
    {
      "id": 3,
      "label": "Retrieval-augmented generation",
      "color": "#6349ea",
      "centroid": [
        120.4,
        -33.1,
        88
      ],
      "size": 312
    }
  ],
  "assignment": [
    3,
    3,
    11,
    "…"
  ]
}

Node detail

GET /api/v1/graph/{case}/nodes/{nodeIndex}

Full metadata for one node.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/nodes/412" \
  -H "X-API-Key: $VOL_API_KEY"

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.node("papers", 412);

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/nodes/412",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

{
  "nodeIndex": 412,
  "id": "paper_412",
  "title": "Graph-augmented retrieval for scientific QA",
  "abstract": "…",
  "year": 2024,
  "venue": "ACL",
  "authors": [
    "A. Researcher",
    "B. Scientist"
  ],
  "url": "https://doi.org/…",
  "citationCount": 37
}

Neighbors

GET /api/v1/graph/{case}/neighbors/{nodeIndex}

Weighted neighbourhood of a node. Query: hops (1 or 2, default 1), limit (default 30).

From the API schema: Breadth-first neighbourhood over the graph edges (1 or 2 hops) plus precomputed similar items. Scores decay with 3D distance to the center. limit caps the number of nodes besides the center.

Auth: API key (X-API-Key) or user session

curl "https://vol.example.com/api/v1/graph/papers/neighbors/412?hops=1&limit=30" \
  -H "X-API-Key: $VOL_API_KEY"

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.neighbors("papers", 412, { hops: 1, limit: 30 });

import os, requests

r = requests.get(
    "https://vol.example.com/api/v1/graph/papers/neighbors/412?hops=1&limit=30",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

{
  "center": [
    412
  ],
  "nodes": [
    {
      "nodeIndex": 412,
      "title": "Graph-augmented retrieval…",
      "score": 1,
      "hop": 0
    },
    {
      "nodeIndex": 977,
      "title": "RAPTOR: recursive abstractive…",
      "score": 0.81,
      "hop": 1
    }
  ],
  "edges": [
    [
      412,
      977,
      0.81
    ]
  ]
}

Subgraph

POST /api/v1/graph/{case}/subgraph

Union of neighbourhoods for several nodes — typically all citations of an answer.

From the API schema: Same as neighbors but for a set of centers (e.g. all nodes cited by an answer).

Auth: API key (X-API-Key) or user session

Request body

{
  "nodeIndices": [
    412,
    977
  ],
  "hops": 1,
  "limit": 30
}

curl -X POST "https://vol.example.com/api/v1/graph/papers/subgraph" \
  -H "X-API-Key: $VOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeIndices":[412,977],"hops":1,"limit":30}'

import { VolClient } from "@vol/sdk";

const vol = new VolClient({ baseUrl: "https://vol.example.com/api", apiKey: process.env.VOL_API_KEY });
await vol.graph.subgraph("papers", [412, 977], { hops: 1 });

import os, requests

r = requests.post(
    "https://vol.example.com/api/v1/graph/papers/subgraph",
    headers={"X-API-Key": os.environ["VOL_API_KEY"]},
    json={
      "nodeIndices": [
        412,
        977
      ],
      "hops": 1,
      "limit": 30
    },
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response 200

{
  "center": [
    412
  ],
  "nodes": [
    {
      "nodeIndex": 412,
      "title": "Graph-augmented retrieval…",
      "score": 1,
      "hop": 0
    },
    {
      "nodeIndex": 977,
      "title": "RAPTOR: recursive abstractive…",
      "score": 0.81,
      "hop": 1
    }
  ],
  "edges": [
    [
      412,
      977,
      0.81
    ]
  ]
}

Types

interface GraphMeta {
  case: CaseId; version: string; nodes: number; links: number;
  bounds: { min: [number, number, number]; max: [number, number, number] };
  clusters: number;
}

type CaseId = "papers" | "cordis" | "patents" | "trials";

interface ClustersFile { clusters: ClusterInfo[]; assignment: number[]  }

interface ClusterInfo { id: number; label: string; color: string ; centroid: [number, number, number]; size: number }

interface NodeDetail {
  nodeIndex: number; id: string; title: string; abstract?: string; year?: number; venue?: string;
  authors?: string[]; url?: string; citationCount?: number; extra?: Record<string, unknown>;
}

interface Subgraph { center: number[]; nodes: SubgraphNode[]; edges: [number, number, number][]  }

interface SubgraphNode { nodeIndex: number; title: string; score: number; hop: 0 | 1 | 2 }