KG tools

Three tools for querying the knowledge graph built by POST .../knowledge-graph/builds. All return coverage reporting files withheld by the access predicate. All return 409 kg_not_built when no graph exists for the workspace.

KG info

GET /v1/workspaces/{workspace_id}/tools/kg-info

Snapshot metadata for the workspace knowledge graph. Call this first to confirm the graph exists and to discover hub node IDs for kg-walk. Cost class: cacheable. Query parameters:

path_prefix (optional) — Scope node/edge counts to files under this prefix.
include_graph (optional, default false) — Also return a drawable sample subgraph.
graph_nodes (optional, default 150, max 500) — Node budget for the sample. Ignored when include_graph=false.

curl "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-info?include_graph=false" \
  -H "X-API-Key: $NDI_API_KEY"

Response:

{
  "snapshot_id": "snap-abc123",
  "built_at": "2026-08-09T12:30:00Z",
  "node_types": [
    {"type": "Organization", "count": 142},
    {"type": "Person", "count": 88}
  ],
  "edge_types": [
    {"type": "subsidiary_of", "count": 47}
  ],
  "node_total": 1247,
  "edge_total": 3156,
  "hubs": [
    {"node_id": "node-42", "node_type": "Organization", "title": "Acme Corp", "degree": 210}
  ],
  "path_prefix": null,
  "coverage": {"restricted_candidates": 0, "labels_required": []},
  "graph": null
}

Response fields:

snapshot_id — Changes when the graph is rebuilt; use to detect staleness.
node_types / edge_types — Counts by type.
hubs — Highest-degree nodes in the caller-visible slice (good kg-walk starting points).
graph — Drawable subgraph sample when include_graph=true; null otherwise.

KG search

POST /v1/workspaces/{workspace_id}/tools/kg-search

Find graph nodes by semantic similarity to a query. Returns nodes with their facts and source-file provenance. Cost class: medium. Request body:

{
  "query": "subsidiaries of Acme Corp",
  "k": 10,
  "node_types": ["Organization"],
  "path_prefix": null
}

Body fields:

query (required, max 4096 chars) — Natural-language or keyword search.
k (optional, default 10, max 100) — Number of results.
node_types (optional) — Restrict to a subset of node types from kg-info.
path_prefix (optional) — Restrict to nodes sourced from files under this prefix.

curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-search" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "subsidiaries of Acme Corp", "k": 5}'

Response:

{
  "nodes": [
    {
      "node_id": "node-43",
      "node_type": "Organization",
      "title": "Subsidiary Y",
      "facts": [
        {
          "predicate": "incorporated_in",
          "value": "Delaware",
          "evidence": {"file_id": "...", "path": "report.pdf", "locator": {...}, "snippet": "...", "relevance_score": 0.95, "why": "...", "component": "certificate_of_incorporation"}
        }
      ],
      "source_files": [{"file_id": "...", "path": "report.pdf"}],
      "degree": 12
    }
  ],
  "coverage": {"restricted_candidates": 0, "labels_required": []}
}

Each fact’s evidence.component names the public component of the source file the fact was extracted from — a spreadsheet tab name or a split document’s section — exactly what qa-file / read-file accept as component=, so a fact hands off directly to a targeted read. For document sections the locator’s page is a real source page and is kept alongside component; for spreadsheet facts the locator carries no page (tabs have no pages — address the tab by component), and the tab name is best-effort — a fact from a small tab processed together with its neighbors can name an adjacent tab of the same file. component is null for single-component files or when attribution is unavailable.

KG walk

POST /v1/workspaces/{workspace_id}/tools/kg-walk

Traverse the graph from a set of seed nodes, following relationships up to a hop limit. Returns nodes, edges, and the paths that explain why each node was reached. Cost class: medium. Request body:

{
  "start_node_ids": ["node-42"],
  "hops": 2,
  "edge_types": null,
  "node_types": null,
  "max_nodes": 100,
  "path_prefix": null
}

Body fields:

start_node_ids (required, 1–50) — Node IDs from kg-info hubs or kg-search results.
hops (optional, default 2, max 5) — Breadth-first hop budget.
edge_types (optional) — Restrict traversal to these edge types.
node_types (optional) — Include only these node types in the result.
max_nodes (optional, default 100, max 500) — Maximum nodes to return.
path_prefix (optional) — Restrict to nodes sourced from files under this prefix. A walk cannot traverse out of scope and back in.

curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-walk" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_node_ids": ["node-42"], "hops": 2}'

Response:

{
  "nodes": [
    {"node_id": "node-42", "node_type": "Organization", "title": "Acme Corp", "facts": [...], "source_files": [...], "degree": 210},
    {"node_id": "node-43", "node_type": "Organization", "title": "Subsidiary Y", "facts": [...], "source_files": [...], "degree": 12}
  ],
  "edges": [
    {"edge_id": "edge-1", "edge_type": "subsidiary_of", "from_node_id": "node-43", "to_node_id": "node-42", "evidence": {...}}
  ],
  "paths": [
    {"node_ids": ["node-42", "node-43"], "edge_ids": ["edge-1"]}
  ],
  "truncated": false,
  "coverage": {"restricted_candidates": 0, "labels_required": []}
}

Response fields:

nodes — All reached nodes with facts and provenance.
edges — Edges traversed, with optional evidence. Edge evidence carries the same component handoff as kg-search facts: pass it to qa-file / read-file as component= (spreadsheet-tab evidence has component and no page; document evidence keeps its real page).
paths — The hop sequences justifying each node’s inclusion.
truncated — true when max_nodes was hit before the walk was complete.

Typical workflow

# 1. Confirm the graph exists and get hub node IDs
curl "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-info" -H "X-API-Key: $NDI_API_KEY"

# 2. Find entities by query
curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-search" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "revenue recognition policy", "k": 5}'

# 3. Walk from discovered nodes
curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-walk" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_node_ids": ["node-42"], "hops": 2}'

Granular operations

Platform resources

Knowledge graph

Tools

Operations

KG info

KG search

KG walk

Typical workflow

​KG info

​KG search

​KG walk

​Typical workflow

KG info

KG search

KG walk

Typical workflow