Citations

You built a beautiful document Q&A feature. Claude reads a 200-page regulatory filing and answers user questions about it. Every answer is well-written, coherent, and plausible. Then a user asks: "Where in the document does it say that?" — and your app has no good answer, because from your code's perspective Claude just returned a string with no trail back to the source. Citations fix this: Claude returns, alongside each claim, the exact passage from your document that supports it.

Why citations matter in production

Without citations, your app is a black box. The user has to trust that Claude's answer is grounded in the document you provided and isn't just drifting into training data. For casual use, that trust might be fine. For anything regulatory, legal, medical, financial, or compliance-adjacent, it isn't — users need to verify, auditors need a trail, and "the AI said so" is not a defensible position.

Citations transform Claude from a black box into a transparent research assistant. Every statement comes with a pointer to the source passage. Users can check the original document. UI designers can build hoverable citation markers. Compliance reviewers can audit the answer against the ground truth. The model is still doing the reasoning, but now the reasoning is traceable.

Enabling citations on a document block

You enable citations by adding two fields to your document block: a human-readable title and the citations: {enabled: True} flag.

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": file_bytes,
    },
    "title": "earth.pdf",
    "citations": {"enabled": True},
}

Two new fields:

• title — a readable name you choose for the document. This is what Claude reports in each citation. Using the filename is a reasonable default, but it can be anything that makes sense to your users ("Q3 2024 Earnings Call Transcript", "RFC 9110", "Employee Handbook v3.2").
• citations: {enabled: True} — the flag that turns the whole feature on.

That's the entire enablement. Add those two fields to any document block (PDF or plain text), and Claude will return citation-annotated responses.

What the response looks like

When citations are enabled, responses become structurally richer. Instead of a single text block, you get a sequence of text and citation objects that together form the answer. Each citation carries:

• cited_text — the exact text from your document that supports the preceding claim. Not a paraphrase — the literal string.
• document_index — which of your provided documents this citation points into. Useful when you hand Claude more than one document in the same request.
• document_title — the title you assigned to that document.
• start_page_number / end_page_number — for PDFs, the page range the cited text spans.
• start_char_index / end_char_index — for plain-text sources, the character offsets (see below).

Your rendering code iterates the response content, interleaving text and citations in the order they appear. The user sees "the atmosphere formed primarily from volcanic outgassing [1][2]" with [1] and [2] being clickable or hoverable citation markers that reveal the source passages when triggered.

Citations with plain text

Citations aren't limited to PDFs. Plain text sources work identically, with one small difference: instead of page numbers, citations reference character positions into the source string.

{
    "type": "document",
    "source": {
        "type": "text",
        "media_type": "text/plain",
        "data": article_text,
    },
    "title": "earth_article",
    "citations": {"enabled": True},
}

The citation objects now include start_char_index and end_char_index fields identifying the exact substring. You can use these offsets to highlight the cited passage in your UI — slice article_text[start_char_index:end_char_index] and render it with an underline, a highlight, or a popover.

Plain text citations are especially useful when you already have the source as a string — a scraped web page, a database field, a user-pasted block. Rather than converting everything to PDF, pass the text directly and get character-level citations back.

Building a UI around citations

The output format is designed to plug straight into a reading UI. Patterns that work well:

• Inline citation markers — render [1], [2], [3] inline with Claude's text, each linked to a source passage.
• Hover cards — when the user hovers a citation marker, show a popup with the cited text and the document title.
• Source panel — render a side panel listing all the sources used, in the order they were cited.
• Click-through — allow users to click a citation and jump to the exact page or character range in the original document.
• Verification mode — for compliance workflows, display every cited passage alongside the claim and require the user to acknowledge each one before finalising.

The point is that the machine-readable structure of citations lets you build genuinely useful transparency features instead of just displaying a disclaimer.

When citations are worth turning on

Always, when:

• Users need to verify information for accuracy.
• The documents are authoritative and users should be able to check them.
• Transparency about information sources is a product requirement.
• Compliance, legal, or regulatory use cases demand an audit trail.
• Users might want to explore the broader context around a specific claim.

Maybe skip, when:

• The output is ephemeral chat and no one is going to click anything.
• Token cost is a constraint and the structured response is heavier than a plain one.
• You're working with very small documents where "the whole document" is effectively one source anyway.

For most document-heavy production use cases, the answer is "turn them on." The upside is traceability and trust; the downside is a slightly richer response schema to parse — and once you've written the parser once, it's boilerplate you never touch again.

Citations are one of the features that move Claude from "useful toy" to "auditable production system." They cost basically nothing to enable, they compound with your existing document workflows, and they give your users the one thing a pure-prose AI answer can't: proof.