GET /v1/understanding
Query the Understanding layer — synthesized, versioned concepts and themes across a scope.
Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Query Parameters
Embedding vectors are omitted from responses by default; pass true to include summary_embedding.
falseResponse Body
curl -X GET "https://example.com/v1/understanding"Understanding needs enrichment
The Understanding layer is synthesized by an LLM and is empty on a content-only self-hosted instance. See Self-hosting defaults.
Concept item shape
Real item shape (v0.9.9)
A concept is { id, scope, ..., supported_by: { events: [...] }, version, stance, staleness_score, support_loss_fraction, coverage_score, synthesis_inputs: { layers, filters, as_of, synthesizer, synthesizer_version }, last_synthesized_at }. Corrections: id (not concept_id; prefix
concept_); no topic field; supported_by (not supports), an object keyed by layer;
no related field in list items (relations are via the /related sub-endpoint). Concepts are
versioned (version).
Behavior notes
- List envelope is
{ items, has_more }— there is no_partialflag (the synthesizer has shipped; drop any "_partial: trueuntil it ships" expectation). - Because concepts carry no
topic, the?topic=filter and the coverageby_topicbreakdown have no field to work on. GET /v1/understanding/{id}→200(with or without?scope);GET /v1/understanding/{id}/related→{ items, has_more }(relation enumspecializes / generalizes / contrasts / co_occurs / causes).GET /v1/understanding/coverage→{ scope, concept_count, avg_confidence, avg_coverage_score, avg_staleness_score, synthesis_lag, _partial }— flat averages, noby_topic.- Concepts are also reachable directly:
GET /v1/concepts?scope=returns the same paginated list envelope{ items, has_more }(verified live), andGET /v1/concepts/{id}/historyreturns a concept's semantic-delta version history — superseded versions carrytemporal.recorded_toclosed. (These aren't in the OpenAPI surface; the shapes above are the live v0.9.9 payloads.) POST /v1/understanding/synthesize { scope, topics }→202{ job_id, status: "running", lifecycle_stream }(job id prefixjob_). Self-hosted, the synthesizer is the configured answer/synth model (e.g.gpt-4o). Synthesis is costly — scope it.
include_vectors is a no-op on all three list GETs
include_vectors=true does not add summary_embedding on GET /v1/understanding, GET /v1/facts, or
GET /v1/beliefs — it stays absent. Embeddings appear only in the */build and */synthesize
responses.