Claude’s Citations API and manual quote-prompting both ground an answer in exact source text, but they split the work differently: the API chunks your documents and returns structured citation objects automatically, while quote-prompting makes Claude do that extraction inline, in plain text, inside its own response. Which one is better depends on whether you’re building a product that needs machine-readable references or just want a more trustworthy answer in a single chat turn.
What the Citations API Actually Does
Citations is a feature of the Messages API, not a separate model or endpoint, and Anthropic’s current documentation says all active models support it. You enable it per document by setting citations.enabled=true inside that document block — currently it has to be enabled on all of the documents in a request or none of them. From there, Anthropic supports three document source types: PDF, plain text, and “custom content.” PDFs and plain text get automatically chunked into sentences, which is the minimum unit Claude can cite — it can point at one sentence or chain several consecutive ones together for a longer passage. Custom content documents skip that automatic chunking entirely and use whatever content blocks you provided as-is, which is the option to reach for if you’re citing from RAG chunks, bullet points, or a transcript where sentence-level chunking isn’t the right granularity.
The response format also depends on which document type you cited from, and this is the part most explainers skip. A citation from a PDF gives you a page number range (1-indexed). A citation from a plain text document gives you a character index range (0-indexed). A citation from a custom content document gives you a content block index range (0-indexed) into the list you originally provided. All three also carry a document index telling you which of the documents in your request the citation came from, counted across every document block in the whole conversation, not just the current message. If your code assumes one citation format and your pipeline later switches from plain text documents to PDFs, that assumption breaks silently unless you branch on the document type.
A Minimal Request
This is Anthropic’s own minimal example, enabling citations on a short plain-text document:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "The grass is green. The sky is blue."
},
"title": "My Document",
"context": "This is a trustworthy document.",
"citations": {"enabled": true}
},
{
"type": "text",
"text": "What color is the grass and sky?"
}
]
}
]
}Two fields are easy to miss on a first read. title and context are both passed to the model but neither counts as citable content — context in particular is useful for stashing document metadata (a source URL, a last-updated date, stringified JSON) since, unlike title, it isn’t length-limited. Only the text inside source can actually be cited from.
Two Things Most Explainers Skip
Citations has two interactions with other API features that aren’t obvious until you hit them in production. First, citations and structured outputs don’t mix: if you enable citations on a document and also set the structured-output format parameter in the same request, the API returns a 400 error, because citations require interleaving citation blocks with text output, which conflicts with the strict schema constraints structured outputs enforce. If your pipeline needs both grounded citations and a strictly-typed response shape, you’ll need to pick one per request, or post-process a citations response into your schema yourself rather than asking the API to do both natively.
Second, citations and prompt caching work together, but not the part you’d expect to cache. The citation blocks Claude generates in its response can’t be cached directly — what you cache is the source document itself, by applying cache_control: {"type": "ephemeral"} to the document’s content block. That’s a meaningful difference if you’re running the same long document through many queries: you’re not caching the answers, you’re caching the material Claude cites from, which is the expensive part to reprocess anyway.
Feature Comparison
| Citations API | Manual quote-prompting | |
|---|---|---|
| Setup | Set citations.enabled=true per document; no prompt engineering required | Write and maintain your own multi-step prompt template |
| Output format | Structured citation blocks with document index, document type, and location range | Plain text; format depends entirely on how you phrased the prompt |
| Document chunking | Automatic sentence-level for PDF/plain text, or fully manual via custom content documents | Not chunked unless you do it yourself before sending the document |
| Citation location format | Page range (PDF), character range (plain text), or content block range (custom content) | Whatever format you instructed in the prompt — no guarantee of consistency |
| Compatible with structured outputs | No — enabling both in the same request returns a 400 error | Yes, if your prompt also specifies a JSON schema for the answer |
| Token cost | Slight input-token increase from chunking; cited_text itself isn’t billed as output tokens, and isn’t re-billed as input on later turns | Every extracted quote and verification step is billed as ordinary output tokens |
| Best fit | Products and pipelines that need to display or log citations programmatically | One-off chat turns, prototypes, or models that don’t offer a native citations feature |
What Manual Quote-Prompting Does Instead
Quote-prompting is a plain-text technique, not an API feature: you instruct Claude, in your prompt, to extract exact quotes from the source material before answering, and to tie each claim in its answer back to one of those quotes. Anthropic’s own prompt-engineering documentation recommends exactly this for long documents — specifically those over roughly 20,000 tokens — as a way to ground responses and reduce hallucinated details, independent of whether you’re also using the Citations API. We covered a full worked version of this as a reusable template in our step-by-step prompt for making Claude cite the exact sentence behind every claim.
The output of quote-prompting lives entirely inside Claude’s text response — bracketed quote numbers, inline citations, whatever format you asked for. There’s no separate structured object your code can parse without you also specifying and enforcing that format yourself, and nothing stops the model from drifting away from the exact format over a long conversation the way a strictly-typed API response can’t.
When to Reach for Each One
- Use the Citations API when you’re building something other code will consume — a support widget that highlights the exact manual passage behind an answer, a research tool that logs every source, or any pipeline where “where did this claim come from” needs to be answered without a human re-reading Claude’s prose.
- Use manual quote-prompting when you’re working in the chat interface directly, prototyping before you’ve committed to an API integration, or using a model that doesn’t offer a native citations feature at all — the technique itself is portable across providers, even though the Citations API is Anthropic-specific.
- Use both together when you want belt-and-suspenders grounding: the API handles the structured citation data for your application, while a lightweight verification instruction in your prompt (something close to Step 3 of the cite-the-exact-sentence template) catches the rare case where Claude’s answer includes a claim that has no citation attached, instead of producing a citation for everything but that one sentence.
How This Relates to the Files API
If your source documents are PDFs you’re sending repeatedly across many requests, pair Citations with the Files API rather than re-uploading the same document on every call. The two are complementary: Files handles not re-sending the same bytes over and over, while Citations handles chunking and referencing what’s inside those bytes once they arrive. Neither replaces the other, and using Files alone doesn’t give you structured citations any more than using Citations alone stops you from re-uploading a document unnecessarily.
What Citations Doesn’t Promise
Neither approach is a hallucination guarantee, and it’s worth saying plainly since the marketing language around grounding features tends to round up. Anthropic’s own announcement describes cited text as something that will “minimize hallucinations,” which is a goal, not a guarantee — the model can still misread a passage it faithfully quotes. A citation proves the text exists in the source and that Claude pulled from it; it doesn’t prove the sentence built around that quote correctly represents what the quote means. Reading the actual cited passage, not just trusting that a citation exists, is still the final check for anything high-stakes — the same caution that applies to tool outputs generally, including when you’re comparing how different providers report how a response was actually generated across Claude, OpenAI, and Gemini.
Featured image: Library bookshelf, CC0 / public domain, via Wikimedia Commons.
FAQ
Can I use Citations and manual quote-prompting in the same request? Yes, and it’s often worth it. Enabling Citations doesn’t stop you from also instructing Claude, in your prompt, to say “I don’t have enough information” when no part of the document answers the question — that fallback behavior is a prompting concern, not an API feature, so it layers on top of Citations rather than competing with it.
Does Citations replace the need to read Anthropic’s own prompting guidance? No. Anthropic’s original Citations announcement and its current API documentation both describe citations as a way to minimize hallucinations, not eliminate them — a citation proves the quoted text exists in your source, not that Claude’s surrounding sentence interprets it correctly. The verification habits from manual quote-prompting are still worth applying as a human-side check, even once the API is doing the extraction for you.
