STEP 2 OF 8

Knowledge Graph

Nothing reaches the Customer Knowledge Graph (CKG) unreviewed. Every document — synced from a connector or uploaded by hand — passes through the Vault (/vault) first, a 3-layer moderation pipeline: Raw → Workspace → Canonical. This guide covers the Vault UI, then the Knowledge Graph page (/knowledge-graph) where approved content becomes queryable entities.

The Vault's three layers

• Raw — an immutable, exact replica of the source. A Slack thread still looks like a Slack thread; a meeting transcript still looks like a transcript. Never modified.
• Workspace — your team's editable moderation copy. Edit, annotate, redact, or flag documents here before they're trusted.
• Canonical — the approved, clean version. Clicking Ingest on a canonical document is what triggers CKG extraction, wiki compilation, and Company Brain indexing.

On /vault, the page header reads "Approval — nothing reaches your Knowledge Graph unreviewed or unfiltered. Raw → Workspace → Canonical." Pick a vault from the selector, browse the document tree, and open the diff/history view (git-backed — every edit is a real commit you can roll back).

# List vaults for your tenant (auto-created per tenant on first connector sync)
curl "https://your-control-plane-host/api/v1/vaults?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Browse a vault's document tree
curl https://your-control-plane-host/api/v1/vaults/{vault_id}/tree \
  -H "Authorization: Bearer $TOKEN"

# Upload a document directly (bypassing a connector entirely)
curl -X POST https://your-control-plane-host/api/v1/vaults/{vault_id}/documents \
  -H "Authorization: Bearer $TOKEN" -F "file=@runbook.pdf" -F "path=runbooks/runbook.pdf"

Approve and ingest

Moderating a document moves it Raw → Workspace → Canonical, then ingestion pushes it into the KG:

# Approve: Workspace -> Canonical
curl -X POST https://your-control-plane-host/api/v1/vaults/{vault_id}/moderate/approve \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"paths": ["runbooks/runbook.pdf"]}'

# Ingest canonical docs into the Knowledge Graph (and Wiki + Brain)
curl -X POST https://your-control-plane-host/api/v1/vaults/{vault_id}/ingest \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"paths": ["runbooks/runbook.pdf"], "target": "all"}'

For sources you already trust, toggle auto-pilot per source from the Vault page (the small toggle next to each source in the connector strip) instead of manually approving every sync — this calls POST /api/v1/vaults/{vault_id}/autopilot with {"source_type": "...", "enabled": true} and skips the review step for future syncs from that source only.

Extraction: how documents become graph nodes

Ingestion runs the N-pass LLM extraction pipeline (app/services/ckg_extraction.py), which reads each canonical document and writes typed entities and relationships as nodes and edges. You can also trigger extraction directly over raw documents (skipping Vault moderation entirely — useful for something like a CI-generated report you don't need a human to review):

curl -X POST https://your-control-plane-host/api/v1/ckg/extract \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"documents": [{"filename": "runbook.md", "content": "..."}]}'
# -> { "id": "<job_id>", "status": "running", ... }

curl https://your-control-plane-host/api/v1/ckg/extractions/{job_id} \
  -H "Authorization: Bearer $TOKEN"

Domains and sub-graphs

/knowledge-graph (labeled Knowledge Graph in the page header) shows the graph broken into domains — an auto-taxonomy, not a hand-authored ontology. As nodes are promoted, the extraction pipeline classifies each one into a domain slug (Finance, IT, Compliance, ...), and any genuinely new slug the model proposes becomes a real registry row (name, description, icon, color) the instant it's proposed. The page shows domain count and total entities/edges, and each domain drills into its own sub-graph.

# The full domain registry tree
curl "https://your-control-plane-host/api/v1/ckg/domains?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Every domain with at least one real node, with rollup counts + a health score
curl "https://your-control-plane-host/api/v1/ckg/sub-graphs?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Nodes + edges for one domain (includes descendant domains, deduplicated)
curl "https://your-control-plane-host/api/v1/ckg/sub-graphs/finance?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Query raw nodes directly
curl "https://your-control-plane-host/api/v1/ckg/nodes?kind=entity" \
  -H "Authorization: Bearer $TOKEN"

Nodes that need a human decision (low confidence, ambiguous merges) land in the review queue (GET /api/v1/ckg/review-queue, POST /api/v1/ckg/review-queue/{item_id}/resolve) — also reachable from the Knowledge Graph page.

What's next

Step 3 — Brain: once entities and relationships exist in the graph, Company Brain can answer questions over them with real citations.