Facts API

Manage deterministic company facts.

List Facts

GET /api/facts

Returns all facts for your organization.

Response

{
  "facts": [
    {
      "id": "uuid",
      "key": "mrr",
      "label": "Monthly Recurring Revenue",
      "scope": "finance",
      "definition": "Total monthly subscription revenue",
      "current_value": {
        "value": "$2.4M",
        "unit": "USD",
        "source_url": "https://dashboard.company.com/mrr",
        "as_of": "2025-01-15T00:00:00Z"
      }
    }
  ]
}

Get Fact

GET /api/facts/[key]

Response

{
  "fact": {
    "key": "mrr",
    "label": "Monthly Recurring Revenue",
    "scope": "finance",
    "definition": "Total monthly subscription revenue",
    "current_value": {
      "value": "$2.4M",
      "unit": "USD",
      "source_url": "https://dashboard.company.com/mrr",
      "as_of": "2025-01-15T00:00:00Z"
    },
    "history": [
      {
        "value": "$2.1M",
        "unit": "USD",
        "source_url": "https://dashboard.company.com/mrr",
        "as_of": "2024-12-15T00:00:00Z"
      }
    ]
  }
}

Create/Update Fact

POST /api/facts

Request Body

Field	Type	Required	Description
`key`	string	Yes	Unique fact key (e.g., `mrr`)
`label`	string	Yes	Human-readable label
`scope`	string	Yes	Required scope to access
`definition`	string	No	What this fact measures
`value`	string	Yes	Current value
`unit`	string	No	Unit of measurement
`source_url`	string	Yes	Citation URL

Response

{
  "ok": true,
  "fact": {
    "id": "uuid",
    "key": "mrr",
    "label": "Monthly Recurring Revenue"
  }
}

Facts are deterministic — they return exact values with citations, never vector-similarity guesses. Use facts for metrics, headcount, financial data, and other authoritative values.

Error Responses

Status	Description
`401`	Not authenticated
`403`	Insufficient scope
`400`	Missing required fields