Citations

Every answer names the passages it came from. This is how to read them.

An answer that cannot show its source is a guess with good grammar. Every grounded answer this API returns names the passages behind it.

What a citation contains

Citations arrive as a list on the assistant's message. Each entry identifies one retrieved passage:

Field	Type	Description
`resource_id`	`uuid`	The resource the passage came from.
`resource_title`	`string`	That resource's title, so you can render a label without a second call.
`chunk_index`	`integer`	Position of the retrieved chunk within the resource.
`metadata`	`object`	Provenance of the passage — page for a PDF, start_time and end_time for audio and video.

metadata carries provenance and varies by document type: page for a PDF, start_time and end_time for audio and video. Use it to deep-link into the source rather than just naming the file.

Parts and sources

The same information appears twice, at two levels of detail. citations is the flat, deduplicated list — the right thing for rendering source chips. response.parts is the structured answer, where each part is a span of text with the single source it came from.

Example

{
  "status": "ok",
  "data": {
    "session": {
      "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37",
      "title": "Anticoagulant discharge window",
      "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f",
      "created_at": "2026-08-05T10:02:11.004Z",
      "updated_at": "2026-08-05T10:02:14.551Z"
    },
    "user_message": {
      "id": "5e2c8a03-49bd-4c17-8f6a-31d0b7e5a924",
      "role": "user",
      "content": "How long do anticoagulant patients stay under observation?",
      "response": null,
      "citations": [],
      "resource_ids": [],
      "image_url": null,
      "created_at": "2026-08-05T10:02:11.219Z"
    },
    "assistant_message": {
      "id": "7c1b4e90-2af6-4d38-b5c1-8e07a3f62d15",
      "role": "assistant",
      "content": "Patients on anticoagulants require a 48-hour observation window before discharge.",
      "response": {
        "type": "answer",
        "parts": [
          {
            "text": "Patients on anticoagulants require a 48-hour observation window before discharge.",
            "source": {
              "chunk_id": "e0c9a71d-5b32-4f88-9a04-6c1d2e83f507",
              "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81",
              "resource_title": "Discharge protocol 2026.pdf",
              "chunk_index": 7,
              "metadata": { "source_type": "pdf", "page": 4 }
            }
          }
        ],
        "form": null
      },
      "citations": [
        {
          "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81",
          "resource_title": "Discharge protocol 2026.pdf",
          "chunk_index": 7,
          "metadata": { "source_type": "pdf", "page": 4 }
        }
      ],
      "resource_ids": ["3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81"],
      "image_url": null,
      "created_at": "2026-08-05T10:02:14.480Z"
    }
  }
}

Use citations if you want to list sources under the answer. Use response.parts if you want to attach each source to the sentence it supports, the way a footnote works.

Some older stored messages were written in a different shape, but the API converts them on read — you only ever need to handle parts.

Rendering them well

Two things worth doing when you display them:

Deduplicate by resource, not by passage. Three passages from one PDF is one source chip, not three.
Link the chip to the document at the cited position using metadata. A citation the reader can't follow is decoration.

An image-only question retrieves against the literal word “image”, so its citations are close to arbitrary. Don't present them as though the model reasoned from those passages.

resource_id

uuid

The resource the passage came from.

resource_title

string

That resource's title, so you can render a label without a second call.

chunk_index

integer

Position of the retrieved chunk within the resource.

metadata

object

Provenance of the passage — page for a PDF, start_time and end_time for audio and video.

{ "status": "ok", "data": { "session": { "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37", "title": "Anticoagulant discharge window", "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f", "created_at": "2026-08-05T10:02:11.004Z", "updated_at": "2026-08-05T10:02:14.551Z" }, "user_message": { "id": "5e2c8a03-49bd-4c17-8f6a-31d0b7e5a924", "role": "user", "content": "How long do anticoagulant patients stay under observation?", "response": null, "citations": [], "resource_ids": [], "image_url": null, "created_at": "2026-08-05T10:02:11.219Z" }, "assistant_message": { "id": "7c1b4e90-2af6-4d38-b5c1-8e07a3f62d15", "role": "assistant", "content": "Patients on anticoagulants require a 48-hour observation window before discharge.", "response": { "type": "answer", "parts": [ { "text": "Patients on anticoagulants require a 48-hour observation window before discharge.", "source": { "chunk_id": "e0c9a71d-5b32-4f88-9a04-6c1d2e83f507", "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81", "resource_title": "Discharge protocol 2026.pdf", "chunk_index": 7, "metadata": { "source_type": "pdf", "page": 4 } } } ], "form": null }, "citations": [ { "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81", "resource_title": "Discharge protocol 2026.pdf", "chunk_index": 7, "metadata": { "source_type": "pdf", "page": 4 } } ], "resource_ids": ["3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81"], "image_url": null, "created_at": "2026-08-05T10:02:14.480Z" } } }

Rendering them well

Two things worth doing when you display them:

Deduplicate by resource, not by passage. Three passages from one PDF is one source chip, not three.

Link the chip to the document at the cited position using metadata. A citation the reader can't follow is decoration.

An image-only question retrieves against the literal word “image”, so its citations are close to arbitrary. Don't present them as though the model reasoned from those passages.