GET /v1/beliefs

curl -X GET "https://example.com/v1/beliefs?scope=string"

curl -X POST "https://example.com/v1/beliefs/build"

Belief item shape

{
  "id": "belief_894c2d0b44946269313446561724778f",
  "scope": "org:acme/team:support",
  "claim": {
    "subject": { "type": "entity", "id": "ent_Amit", "name": "ent_Amit" },
    "predicate": "eats",
    "object": { "type": "literal", "datatype": "string", "value": "fish" }
  },
  "claim_key": { "subject": "ent_amit", "predicate": "eats", "value": "fish",
                 "polarity": "affirmative", "rules_version": 4 },
  "stance": "supported",
  "confidence": 1.0,
  "confidence_interval": { "lower": 0.27, "upper": 1.0, "method": "wilson", "level": 0.9 },
  "supports": [{ "type": "fact", "id": "fact_01HX...", "weight": 1.0, "polarity": "supports" }],
  "revision_policy": { "trigger": "new_supporting_evidence_or_contradiction", "min_evidence_delta": 0.05,
                       "cooldown": "PT5M", "max_revisions_per_hour": 12 },
  "valid_from": "…", "valid_to": null, "recorded_from": "…", "recorded_to": null,
  "last_revised_at": "…",
  "revision_count": 1,
  "supporting_evidence_redacted": false,
  "supporting_evidence_redacted_fraction": 0.0
}

• The key is id. The subject is inside claim.subject (there is no separate about field).
• claim is a triple object; confidence_interval is { lower, upper, method, level }.
• supports is a list of { type, id, weight, polarity }, where polarity is supports or against.

Claim keys and stable ids (v0.10.1)

• claim_key is the form a belief groups and compares on: { subject, predicate, value, polarity, rules_version }, with subject and value folded (lowercase, NFC; ent_Amit → ent_amit, José → josé) and the predicate in the built-in ontology's canonical form (a Hindi "पसंद है" fact extracted as prefers becomes a likes belief). claim keeps the latest supporting fact's own words.
• Belief ids are deterministic: derived from the scope and topic, so rebuilding gives the same ids. Builds before v0.10.1 minted new ids on every build.

Stances

• supported: the evidence backs the claim (a belief built from one uncontested fact).
• contradicted: an affirmative fact and a denial of the same value ("lives in Delhi" / "not Delhi"); the denial is listed in supports with polarity: "against".
• deprecated: the claim ended ("doesn't work at Acme anymore" closed the fact it updates).

A denial of another value ("works at Acme" and "does not work at Globex") is listed as against (weight 0.5) on the first belief and leaves it supported at full confidence.

Filters and sub-endpoints

• Envelope: { items, next_cursor, has_more }. about narrows to one subject (about=ent_Priya); min_confidence, as_of and limit are accepted.
• GET /v1/beliefs/why?belief_id= → { belief, support_graph: { nodes, edges }, narrative, narrative_model }. Self-hosted, narrative_model is the configured answer LLM (e.g. gpt-4o-mini-2024-07-18), not the cloud default.
• POST /v1/beliefs/build { scope } → { built: N, items: [...] } forces a build pass and returns each belief's summary_embedding. GET /v1/beliefs does not return embeddings; use the build response when you need them.