Claude Corner: Uncited Doc Answers → Enable Citations Blocks

• Turn on citations.enabled on every document block so Claude returns structured locations instead of freeform "according to the docs" prose.
• Prefer plain text or PDF for sentence chunking, or custom content blocks when you need RAG-chunk granularity.
• Do not combine citations with output_config.format JSON schema. The API returns 400 because citation spans cannot satisfy a single schema object.

You shipped a RAG answer that sounded sourced and still could not show the sentence. Prompting "cite your sources" produces decorative footnotes. The Messages API can attach citation metadata to text blocks when you enable citations on the documents you already send.

Why it matters

Support and internal Q&A break when operators cannot jump from a claim to a page, character range, or chunk. Prompt-only citation instructions waste output tokens on quoted text and still invent soft references. Anthropic's citations feature chunks your documents, grounds claims, and returns location objects the client can render. cited_text does not count toward output tokens. Enable citations on all documents in the request or on none, keep title and context non-citable, and skip structured outputs on the same call. The one move: set citations.enabled to true on each document block and parse the citation arrays on the text blocks you render.

How to enable document citations

Use the Messages API with a document content block, citations.enabled true, and a real model id from current docs examples (claude-opus-5 below). Put secrets in the environment. Prefer plain text for prose, PDF when you need page numbers, and custom content when each RAG chunk must stay one citable unit.

1. 1. Attach one or more document blocks before the user question. Set citations.enabled to true on every document in the request.
2. 2. Choose a source type: text (sentence chunking, char indices), PDF (base64 or url, page numbers), or content (your blocks, no further chunking).
3. 3. Optionally set title and context for display and non-citable hints. Only source text is citable.
4. 4. On HTTP 200, walk content text blocks and render any citations arrays (char_location, page_location, or content_block_location). Do not enable output_config.format on this request.

#!/usr/bin/env bash
set -euo pipefail
: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY in your environment}"

# Document grounding: citations on the document block, not prompt-only "please cite".
curl -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "text",
              "media_type": "text/plain",
              "data": "Refunds ship within five business days after approval. Express shipping is unavailable on clearance items. Support hours are 09:00-17:00 PT Monday through Friday."
            },
            "title": "Returns policy excerpt",
            "context": "Internal policy snippet for customer support grounding. Not a full legal contract.",
            "citations": {"enabled": true}
          },
          {
            "type": "text",
            "text": "How fast do refunds ship after approval, and can clearance orders use express shipping?"
          }
        ]
      }
    ]
  }'
# Render each text block's citations[].cited_text plus char/page/block indices in your UI.

Gotchas

• Citations must be enabled on all documents in the request or on none. Mixed settings are not supported.
• Citations plus structured outputs (output_config.format / deprecated output_format) return 400. Tip 3's JSON schema path and this tip are alternate reply shapes, not a combo.
• Image citations from PDFs are not supported yet. Scanned PDFs without extractable text are not usefully citable.
• cited_text does not count toward output tokens, and when you pass citation blocks back in later turns it also skips input token counting for that field.
• Prompt caching still works with cache_control on the document block. For finer RAG control, put each retrieved chunk in its own plain text document or use a custom content document with one block per chunk.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever you use.

Sources: Citations · Introducing Citations