GET /v1/facts

Query the Facts layer — typed subject/predicate/object triples with bi-temporal validity.

Authorization

bearer

AuthorizationBearer <token>

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

In: header

Query Parameters

scope*string

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/facts?scope=string"

Empty

Facts from text need enrichment; triple captures do not

Facts extracted from text are LLM-derived, so that part of the layer fills once you configure enrichment (see Self-hosting defaults). A triple capture writes its fact directly, with or without enrichment, and the fact is on this endpoint as soon as a ?wait=indexed write returns.

Fact item shape

A fact is { id, scope, subject: { type, id }, predicate, object: { type, datatype, value }, supports, valid_from, valid_to, recorded_from, recorded_to, confidence, stance, polarity }:

The key is id; subject is { type, id }; object includes its type.
stance is e.g. "supported"; polarity is affirmative, negated or ceased.
A superseded fact adds superseded_by and a closed valid_to.

Facts extracted by v0.10.1 can also carry these optional fields (additive; rely on them once the capability fact_surface_v1 appears in GET /v1/admin/version):

Field	What it holds
`quote`	The exact span of the capture's own text the fact came from
`language`	The source's language tag, e.g. `und-Deva`, `hi-Latn`
`gloss`	For a non-English fact, a derived English key: `{ text_en?, object_en?, derived: true, model, prompt_version }`. It is used for search only and never appears in `context_block` or citations
`date_basis`	How a dated fact got its date: `refers_to`, `verbatim`, `extractor` or `ambiguous`
`date_candidates`	Every reading of an ambiguous day word (the fact is then stamped with none)

Subjects and objects stay in the source script ("प्रिया … चाय"); predicates are English snake_case. Each captured sentence also yields a states fact whose subject is ent_fact_subject_… and whose object is the whole sentence.

Entity ids

A subject's id is ent_ plus its name when the name is pure ASCII (ent_Priya, case-sensitive). Since v0.10.1 a name with any non-ASCII character gets a hashed id: ent_<ascii-base>-<16 hex> when it has ASCII letters (José → ent_jose-0f66606aa13f1258) or ent_u-<16 hex> when it has none (प्रिया → ent_u-0133576006acc0d5). Ids stored by v0.9.13 (such as ent_Jos_) still resolve on reads and forgets.

Negation, cessation and supersession (enrichment on)

A denial of another value retires nothing. "Meera eats fish" and "Meera doesn't eat non-veg", or "Amit works at Acme" and "Amit does not work at Globex", stay live side by side (the denial is stored with polarity: "negated", e.g. works_at | not Globex).
A change of state is an update. "Kavya doesn't work at Acme anymore" closes the earlier fact (valid_to set, superseded_by filled) and leaves its belief deprecated.
A denial of the current value is a contradiction. When the extraction model reads a statement as a denial of the same value (for example "Priya lives in Delhi", then a later statement stored as lives_in | not Delhi), both facts stay, the belief becomes contradicted, and a conflict opens on /v1/conflicts, where you can resolve it. How a change is phrased, and the extraction model you use, decide which of the two it becomes.

Stores written by v0.9.13 and earlier with enrichment on can be repaired with the v0.10.1 derived-data repair routes.

Filters

Filter	What it does
`predicate`	Only facts with that predicate (`predicate=lives_in`).
`subject`	Only that subject's facts (`subject=ent_Priya`).
`min_confidence`	Only facts at or above that confidence (0–1).
`as_of`	Bi-temporal as-of: the value valid at that instant.
`include_superseded`	`true` adds superseded facts.

To narrow by object, filter the results on your side. summary_embedding is not returned on this GET; POST /v1/beliefs/build returns embeddings for beliefs.

Notes

Envelope: { items, next_cursor, has_more }.
GET /v1/facts/timeline?scope=&subject=&predicate= returns { subject, predicate, timeline[] }, the supersession chain; subject there is { id } only, and each entry is { fact_id, value, valid_from, valid_to } (note fact_id here, not id).
A triple capture takes only subject, predicate and object, and stores the fact as affirmative. Negated facts come from extraction.

GET /v1/facts

200

On this page