> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge graph

> Build the workspace knowledge graph — 1 endpoint

A knowledge graph captures semantic relationships between entities across all files
in a workspace. Entity resolution runs corpus-wide, so the graph is built as one
operation, not per file.

To query the graph after building, use the [KG tools](/api-reference/kg-tools):
`kg-info`, `kg-search`, and `kg-walk`.

***

## Build knowledge graph

```
POST /v1/workspaces/{workspace_id}/knowledge-graph/builds
```

Build or rebuild the workspace knowledge graph from its ingested files. Files that are
not yet ingested are not in the corpus — ingest them first.

**Query parameters:**

* **`wait_seconds`** (optional, default 0, max 300) — A real build far outlasts any sync window; callers normally poll the returned job.

**Headers:**

* **`Idempotency-Key`** (optional)

**Request body:**

```json theme={"dark"}
{
  "force": false
}
```

**Body fields:**

* **`force`** (optional, default `false`) — Clear the workspace's graph store and rebuild from scratch. The default resumes from the durable store, reusing prior extraction and resolution work. Use `force` only when the store is suspected corrupt or the ontology's meaning changed under a version it did not re-key.

```bash theme={"dark"}
curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/knowledge-graph/builds" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Response (202 Accepted):** A `Job` with `kind: "kg_build"`.

**Result (on success):**

```json theme={"dark"}
{
  "result_type": "kg_build",
  "snapshot_id": "snap-abc123",
  "files_covered": 42,
  "node_count": 1247,
  "edge_count": 3156,
  "rebuilt": false,
  "files_failed": [
    {
      "path": "reports/damaged-scan.pdf",
      "phase": "extracting",
      "error": "The document could not be parsed"
    }
  ]
}
```

**Result fields:**

* **`snapshot_id`** — Cache key for this graph version. Changes each time the graph is rebuilt; use it to detect staleness.
* **`files_covered`** — Source files whose ledger version matched the build-time corpus at finalization.
* **`node_count`** / **`edge_count`** — Totals for the built graph.
* **`rebuilt`** — `true` when a `force` build cleared the prior store first.
* **`files_failed`** — Files excluded after exhausting their retries. Each entry reports the source `path`, failure `phase` (`classifying` or `extracting`), and final `error`. These files are not included in `files_covered` and remain eligible for a later rebuild.

***

## Auto-build

`knowledge_graph.auto_build` is **off by default**: a build is billable and
long-running, so ingesting files does not start one for you.

Set it to `true` — at creation or later via
[Update workspace](/api-reference/workspaces#update-workspace) — for a workspace that
should hold a graph over everything it ingests. Each ingestion then chains a build
after file processing, and the `ingestion` job result carries `kg_build_job_id`
pointing at it. Nothing else changes: those builds are the same `kg_build` jobs,
report the same `progress`, and are stopped the same way with
[Cancel job](/api-reference/jobs#cancel-job).

***

## Prerequisites

1. Files must be uploaded and ingested before a build covers them.
2. A build is corpus-level — it reads all ingested files at once.
3. Only one build can be queued at a time per workspace.

***

## Errors

* **`kg_build_in_progress`** (409) — A build is already running; wait for it to finish.
* **`workspace_deleting`** (409) — The workspace is being torn down.