When you attach documents to a request, you can ask Claude to ground its answer in them: every claim in the response comes back linked to the exact passage it relied on. Unlike prompting the model to "quote your sources" — which produces free-text quotes you then have to parse and verify — citations are structured objects in the API response, ready to render as footnotes, highlight in a viewer, or log into an audit trail.
Enabling citations
Citations are enabled per document, not per request. Add "citations": {"enabled": true} to each document content block you want Claude to cite from. It is a standard Messages API feature — no beta header — and every active model supports it except Claude Haiku 3.
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")
msg = client.messages.create(
model="claude-sonnet-5", max_tokens=1024,
messages=[{"role": "user", "content": [
{"type": "document",
"source": {"type": "text", "media_type": "text/plain",
"data": open("policy.txt").read()},
"title": "Expense Policy",
"citations": {"enabled": True}},
{"type": "text", "text": "What is the per-diem limit for travel?"},
]}],
)What comes back, and the three location formats
The response's text blocks carry a list of citation objects. Each includes the cited_text itself and a document_index telling you which attached document it came from, plus location fields whose shape depends on the document type:
| Document type | Citation format | Granularity |
|---|---|---|
| Plain text | char_location | Sentence-level (the API chunks text into sentences) |
page_location | Page numbers; text is extracted and sentence-chunked | |
| Custom content | content_block_location | Your own blocks, used as-is (0-indexed, exclusive end) |
For retrieval-augmented generation (RAG) pipelines, this gives you two levers on granularity: put each retrieved chunk in its own plain-text document to get sentence-level citations within it, or use custom content documents when you want Claude to cite your chunks exactly as you supplied them, with no further chunking.
Rendering is straightforward: walk the response content, and wherever a text block carries citations, emit a footnote marker keyed on document_index plus the location, and show cited_text in the tooltip or appendix. For audit trails, log the citation objects verbatim next to the generated answer — they are the evidence.
Cost behavior — mostly favorable
Enabling citations slightly increases input tokens: the API adds system-prompt instructions and chunks your documents. But it is efficient on the output side — cited_text does not count toward output tokens, and when a cited response is passed back in later turns of the conversation, the cited text doesn't count toward input tokens either. Compared to prompting the model to reproduce quotes in its answer, structured citations are usually cheaper.
Limits worth knowing before you commit
Scanned PDFs don't cite. Citing images inside PDFs is not supported, so a scanned document with no extractable text layer cannot produce citations. Run OCR (optical character recognition) upstream if your document estate is scan-heavy.
Citations and structured outputs are mutually exclusive. Enabling citations on any document or search-result block in a request that also sets output_config.format returns a 400 error. If you need both grounded answers and schema-valid JSON, you must pick one per request — a common pattern is a citations pass followed by a formatting pass.
Platform status. Citations are generally available on the Claude API, Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry. One Bedrock-specific interaction: on the Converse API, full visual understanding of PDFs requires citations to be enabled — without them, PDF handling falls back to text-only extraction. Citations are also eligible for Zero Data Retention, which matters if your organization runs a ZDR agreement on the first-party API.
Where to go next
Citations pair naturally with PDF support and RAG-style document injection. If you were planning to combine them with JSON output, read strict tool use for the alternative. The feature matrix shows platform coverage at a glance.