How to Add Citations to Claude API Responses

To add citations to Claude API responses, set 'citations': {'enabled': True} on each document block you include in your user message. Claude then automatically breaks the document into chunks, generates a response, and attaches structured citation objects to each factual claim—pointing back to exact character ranges, page numbers, or block indices in your source material. No complex prompt engineering required.

What Is the Claude Citations API?

The Citations feature in the Anthropic Messages API enables Claude to automatically attach precise source references to the claims it makes when answering questions about user-provided documents. Instead of requiring developers to engineer complex prompts to extract verbatim quotes, the API handles document chunking internally and interleaves the generated response text with structured citation objects that point back to exact locations in the source material.

Depending on the document type you provide, citations reference:

• Plain text documents — character index ranges (start and end character positions)
• PDFs — page ranges (specific page numbers within the document)
• Custom content blocks — block index ranges (developer-defined chunks)

The cited_text field returned in each citation object is provided as a convenience and does not count toward output token billing, making citations more cost-effective than they might initially appear.

How Do You Enable Citations on a Claude API Request?

The core pattern is straightforward. Here is a minimal working example using a plain text document:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=256,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "text",
                    "media_type": "text/plain",
                    "data": "The grass is green. The sky is blue."
                },
                "title": "Nature Facts",
                "citations": {"enabled": True}
            },
            {"type": "text", "text": "What color is the grass and sky?"}
        ]
    }]
)
print(response.content)

The response will contain a series of text blocks. Each block that makes a factual claim will carry a citations array with objects describing the exact source location. For plain text, you will see char_location citation types with start_char_index and end_char_index fields. For PDFs, you will see page_location types with page numbers.

What Are the Step-by-Step Instructions for Adding Citations?

1. Create an API client — Instantiate an Anthropic client using your API key.
2. Prepare your source document — Supported formats include a plain text string, a base64-encoded PDF, a file ID referencing an uploaded file via the Files API, or a list of custom content blocks.
3. Build the document block — Include the document as a document block in the content array of your user message, and set 'citations': {'enabled': True} on each document you want cited.
4. Add your question — Place a text block with your question or instruction after the document block(s) in the same content array.
5. Send the request — Call client.messages.create(...) specifying a supported model. Note that Claude Haiku 3 does not support citations.
6. Parse the response — Each text block in response.content may have a citations array. Each citation object contains a type, document_index, document_title, cited_text, and location fields.
7. (Optional) Use the Files API — For documents already uploaded via the Files API, include the appropriate beta header and reference files by file_id in the document source.

How Do You Handle PDF Documents with Page-Level Citations?

For PDF documents, base64-encode the file and set the source type accordingly:

import anthropic, base64

client = anthropic.Anthropic()

with open("annual_report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=512,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Annual Report 2024",
                "citations": {"enabled": True}
            },
            {"type": "text", "text": "What were the main revenue drivers in Q3?"}
        ]
    }]
)

The citation objects in the response will be of type page_location, giving you specific page numbers that map directly to what a human sees in a document viewer. This makes it straightforward to build a "jump to source" feature in legal, financial, or research applications.

According to the Anthropic Citations API announcement, the feature is designed precisely for applications where verifiability and source attribution matter—including legal research tools, financial document analysis, enterprise RAG pipelines, compliance workflows, and customer support systems.

How Do You Work with Multiple Documents?

You can include multiple document blocks in a single request. Each document gets its own document_index (starting at 0), and citation objects reference this index so your application always knows which source a claim came from:

messages=[{
    "role": "user",
    "content": [
        {
            "type": "document",
            "source": {"type": "text", "media_type": "text/plain",
                       "data": "Q: How do I reset my password?\nA: Go to Settings > Security > Reset Password."},
            "title": "FAQ",
            "citations": {"enabled": True}
        },
        {
            "type": "document",
            "source": {"type": "base64", "media_type": "application/pdf", "data": pdf_b64},
            "title": "Product Manual",
            "citations": {"enabled": True}
        },
        {"type": "text", "text": "How do I reset my password and what security options are available?"}
    ]
}]

Claims drawn from the FAQ will carry document_index: 0; claims from the manual will carry document_index: 1. This makes multi-source attribution trivial without additional post-processing logic.

When Should You Use the Citations API vs. Other Approaches?

What Are the Most Common Pitfalls When Adding Citations?

• Combining citations with structured outputs — Do not include structured output format parameters in the same request as citations. The API will return an error because these two features are mutually exclusive.
• Forgetting to enable citations on every document block — Citations must be explicitly enabled per document block. A document without the flag will not produce citations even if other documents in the same request have it enabled.
• Passing scanned (image-only) PDFs — Citations work on extractable text layers. Scanned documents that contain only rasterized images have no text for the API to chunk and cite. Run OCR first, or extract text manually and pass it as a plain text document block.
• Using unsupported document formats — The Citations API natively supports PDFs and plain text only. Convert formats like spreadsheets or word processor files to plain text before passing them as document blocks.
• Re-processing the same large documents on every call — For documents that remain constant across requests, consider adding cache control to document blocks. The source document content can be cached, significantly reducing processing time and cost for repeated queries over the same corpus.

Where Is the Citations API Available?

The Citations API is available at no additional cost beyond standard token pricing. It is supported on the direct Anthropic Messages API, Amazon Bedrock, and Google Cloud Vertex AI. The feature works across all current Claude models with the exception of Claude Haiku 3. Custom content blocks—which give developers control over citation chunk granularity—are also supported, making it possible to cite individual database records, transcript segments, or structured entries rather than relying on automatic sentence-level chunking.