Citations

Citations let agents formally reference specific document sources. Unlike retrieval (which tracks what an agent had access to), citations record what an agent used as a source for its response.

How Citations Work

When an agent or workflow step needs to formally reference a document, it calls the resolve_citation platform function. This creates a citation record linking the execution context (chat session, workflow, function call) to a specific document chunk at a specific revision.

Agent retrieves chunks via search_docs
    → Agent reasons about the content
    → Agent calls resolve_citation to formally cite a source
    → Citation stored with verification result

Platform Functions

resolve_citation

Creates a citation linking an execution context to a document chunk.

Parameters:

Parameter	Type	Required	Description
chunk_id	string (UUID)	Yes	The document chunk being cited
quoted_text	string	No	Exact text being referenced (enables verification)

Returns: Citation object with id, verification_status, match_type, and source metadata.

When quoted_text is provided, the system verifies it against the chunk content:

Match Type	Description
exact	Quoted text found verbatim in chunk
normalized	Match after whitespace normalization
fuzzy	High similarity match (>85%)
not_found	No match found — citation still created but marked as failed

verify_citation

Re-verifies an existing citation against its source chunk. Useful when documents are updated.

Parameters:

Parameter	Type	Required	Description
citation_id	string (UUID)	Yes	The citation to verify

Returns: Updated citation with fresh verification_status and match_type.

REST API

List citations

GET /api/citations?tenant_id=tenant1&document_id=abc123

Query parameters: tenant_id (required), document_id, collection_id, execution_context_type, execution_context_id, verification_status, document_name, date_from, date_to, skip, limit.

• document_name — case-insensitive partial match (ILIKE)
• date_from / date_to — filter by created_at range (ISO 8601 datetime)

Get citation

GET /api/citations/{citation_id}

Citation stats

GET /api/citations/stats?tenant_id=tenant1

Returns counts grouped by verification_status: verified, failed, pending, unverified, out_of_provenance, and a computed total.

Chat citation status (client-auth)

GET /api/chat/{session_id}/citation/{chunk_id}/{revision_id}/status

Returns verification status of a specific citation within a chat session. Used by the chat widget to show citation detail. Requires X-API-Key header (client auth, not admin auth).

Response:

{
  "found": true,
  "verification_status": "verified",
  "match_type": "exact",
  "match_score": 1.0,
  "matched_span_start": 10,
  "matched_span_end": 50,
  "verified_at": "2026-02-20T10:30:00Z"
}

In the chat widget

When agents include <citations> XML blocks in their responses, the chat widget:

1. Parses the block — extracts citation objects with ref, chunk_id, revision_id, doc_name, optional page, section, quote, and match_type.
2. Renders inline markers — superscript [N] badges after cited text.
3. Shows a footer — ordered list of citations below the message with document name, page, and verification icon.
4. Opens a bottom sheet — tapping a citation shows full detail with quoted text, verification badge, and copy action.

The widget fetches live verification status from the chat citation status endpoint when a session ID is available.

In the admin panel

The Documents page includes a Citations tab with:

• Stats cards — total, verified, failed, and pending counts with percentages
• Filterable table — search by document name, filter by status and date range
• Detail panel — slide-over showing verification badge, match score, source info, and quoted text
• Document preview integration — each document's preview shows a citations summary with recent references

Design Decisions

• No foreign keys to chunks/revisions — citations outlive their sources. If a document is deleted, the citation remains as a historical record with its document_name snapshot.
• Verification is optional — citations without quoted_text are stored as unverified. This supports use cases where the agent references a whole chunk rather than a specific passage.
• Tenant-scoped — all citation queries filter by tenant_id, consistent with the rest of the platform.