Skip to main content
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: kg-info, kg-search, and kg-walk.

​
Build knowledge graph

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:
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.
Response (202 Accepted): A Job with kind: "kg_build". Result (on success):
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 — 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.

​
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.