Understanding

Understanding is the synthesized concept layer: LLM-extracted concepts, themes, and relationships about a scope. Built async; the responses carry _partial: true until the synthesizer ships fully.

Stability: beta for reads; experimental for POST /v1/understanding/synthesize.

---

GET /v1/understanding

GET /v1/understanding
  ?scope=org:acme/dept:eng
  &topic=B2B+SaaS
  &depth=2
  &limit=50

Response

{
  "items": [
    {
      "concept_id": "cn_01HX...",
      "scope":      "org:acme/dept:eng",
      "name":       "Q3 renewal motion",
      "topic":      "sales_process",
      "version":    7,
      "summary":    "Multi-touch renewal cycle starting with POC extension at quarter mark...",
      "supports":   ["fact_01HX...", "ep_01HX..."],
      "related":    [{ "concept_id": "cn_01HY...", "relation": "specializes" }],
      "confidence": 0.74,
      "valid_from": "2026-05-10T00:00:00Z"
    }
  ],
  "_partial": true
}

---

GET /v1/understanding/

Returns the full concept record.

---

GET /v1/understanding//related

Walks the relation graph from a concept.

GET /v1/understanding/{concept_id}/related
  ?relation=specializes
  &depth=2
  &limit=50

relation ∈ { specializes, generalizes, contrasts, co_occurs, causes }.

---

GET /v1/understanding/coverage

A snapshot of synthesis coverage across topics in a scope.

GET /v1/understanding/coverage?scope=org:acme/dept:eng

Response

{
  "scope": "org:acme/dept:eng",
  "concept_count": 421,
  "by_topic": [
    { "topic": "sales_process",     "concepts": 38, "avg_confidence": 0.74 },
    { "topic": "product_features",  "concepts": 92, "avg_confidence": 0.81 },
    { "topic": "customer_personas", "concepts": 24, "avg_confidence": 0.62 }
  ],
  "synthesis_lag": "P2D",
  "_partial": true
}

---

POST /v1/understanding/synthesize

Capability: understanding.synthesize

Trigger an on-demand synthesis pass for a scope. Returns 202 with a lifecycle stream URL. Stability: experimental.

{
  "scope": "org:acme/dept:eng",
  "topics": ["sales_process"],
  "force": false
}

Response

{
  "job_id": "synth_01HX...",
  "status": "running",
  "lifecycle_stream": "/v1/lifecycle/stream?job_id=synth_01HX..."
}

If the synthesizer isn't configured, returns 503 with SYNTHESIZER_UNCONFIGURED.