How citations work

Every factual claim in a Cortex answer points to one passage. This page explains how those passages are chosen, why some are set aside, and how to read the result through the API.

1. Finding passages

When you ask a question, Cortex searches the knowledge bases attached to the conversation and returns the eight passages that match best. Each one gets a match score between 0 and 1. Passages below the workspace minimum, 0.70 by default, are never read.

2. Setting passages aside

Of the passages that clear the minimum, Cortex sets aside any that repeat another passage, fall outside your freshness rule, or turn out not to address the question. The reason is recorded and shown under the answer, so a missing citation is never a mystery.

3. Reading citations through the API

The /v1/ask response lists every passage that was read, with its outcome.

{
  "answer": "Seven of nine teams said…[1]",
  "cost_usd": 0.014,
  "passages": [
    { "cite": 1, "document": "Customer interview synthesis",
      "passage": 118, "match": 0.91, "outcome": "cited" },
    { "cite": null, "document": "Interview round 1 notes",
      "passage": 7, "match": 0.72, "outcome": "stale" }
  ]
}

The outcome field is one of cited, duplicate, stale, off_topic or below_minimum.