GET /v1/understanding

Query the Understanding layer — synthesized, versioned concepts and themes across a scope.

Authorization

bearer

AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.

In: header

Query Parameters

include_vectors?boolean

Embedding vectors are omitted from responses by default; pass true to include summary_embedding.

Defaultfalse

Response Body

curl -X GET "https://example.com/v1/understanding"

Empty

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; concept field set unchanged through the v0.10.1 schema)

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 _partial flag (the synthesizer has shipped; drop any "_partial: true until it ships" expectation).
Because concepts carry no topic, the ?topic= filter and the coverage by_topic breakdown have no field to work on.
GET /v1/understanding/{id} → 200 (with or without ?scope); GET /v1/understanding/{id}/related → { items, has_more } (relation enum specializes / 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, no by_topic.
Concepts are also reachable directly: GET /v1/concepts?scope= returns the same paginated list envelope { items, has_more }, and GET /v1/concepts/{id}/history returns a concept's semantic-delta version history — superseded versions carry temporal.recorded_to closed.
POST /v1/understanding/synthesize { scope, topics } → 202 { job_id, status: "running", lifecycle_stream } (job id prefix job_). Self-hosted, the synthesizer is the configured answer/synth model (e.g. gpt-5.6-terra). Synthesis is costly — scope it.

Where embeddings appear

The list GETs (GET /v1/understanding, GET /v1/facts, GET /v1/beliefs) don't return summary_embedding; the */build and */synthesize responses do.