Facts

Approved company numbers and definitions, to be used verbatim.

A fact is a named value the workspace owner has signed off: a customer count, a price, a tagline. Each has a definition, a current value and the source it was taken from.

Use facts for anything that must be exactly right. Recall finds passages; a fact is the approved figure itself.

List facts

GET /api/v1/facts

Returns every fact in the scopes the key can read.

A content product's key is limited to Publishable, so it sees only the facts the owner has filed there: the prices, counts and taglines cleared for public posts. A budget or an internal target stays out of reach, even when it is filed under marketing.

curl https://<your-buddhi-host>/api/v1/facts \
  -H "Authorization: Bearer crtx_YOUR_KEY"

{
  "facts": [
    {
      "key": "tagline",
      "label": "Company tagline",
      "scopeKey": "marketing",
      "definition": "The approved one-line description of the product.",
      "latest": {
        "value": "Memory your whole company can trust",
        "unit": null,
        "asOf": "2026-09-30T00:00:00.000Z",
        "sourceUrl": "https://www.notion.so/…"
      }
    }
  ]
}

latest is null for a fact that has been defined but has no value yet.

Get one fact

GET /api/v1/facts/:key

curl https://<your-buddhi-host>/api/v1/facts/tagline \
  -H "Authorization: Bearer crtx_YOUR_KEY"

{
  "key": "tagline",
  "label": "Company tagline",
  "definition": "The approved one-line description of the product.",
  "value": "Memory your whole company can trust",
  "unit": null,
  "asOf": "2026-09-30T00:00:00.000Z",
  "sourceUrl": "https://www.notion.so/…"
}

Field	Description
`value`	The current approved value, always a string
`unit`	The unit, such as `USD` or `%`, or `null`
`asOf`	The date the value applies to
`sourceUrl`	Where the value was taken from

A fact returns 404 fact_not_found when the key does not exist, when it has no value yet, or when it lives in a scope the key cannot read. The three are deliberately indistinguishable, so a key cannot find out which facts exist outside its scopes. Every lookup is recorded in the audit log.

Using facts in generated content

Insert the value exactly as returned. Do not let a model rephrase or round it.
Quote asOf when the figure is time-sensitive, for example "as of September 2026".
Facts are read-only through this API. They are created and updated in Facts Registry by the workspace owner.
A fact your product needs but cannot see is not cleared for public use yet. The owner can file it under Publishable, either directly or when approving a fact Buddhi extracted from Slack or GitHub.