A knowledge assistant answers, “The export is retained for 30 days.”
The answer sounds clear. A user still needs to know which document supports it, whether that document applies to the current product, and whether the answer omitted an exception.
Claude’s citations feature can return source references alongside generated text. This creates a stronger foundation for a reviewable document assistant than asking the model to write a source label at the end of its answer.
This tutorial uses Claude Opus 5.5 through the Messages API and focuses on preserving the returned evidence from the model response to the user interface.
1. Use the native citation feature deliberately
There are two different approaches:
| Approach | What the application receives |
|---|---|
| Prompt the model to mention a source | Generated text containing a source label |
| Enable native citations | Text blocks with structured citation information |
A source label written in prose still needs to be interpreted and checked by your application.
Native citation objects provide a defined response structure that your application can retain and display.
Neither approach removes the need to evaluate the answer. A relevant passage can be cited while the generated explanation still overstates what that passage says.
The goal is to make evidence inspectable, not to declare every cited answer correct.
2. Start with one synthetic document
Use a document with a clear rule and an unanswered question.
For example:
Project export policy, revision 3.
Completed exports remain downloadable for 30 days.
This document does not specify how long deleted projects are retained.Ask two questions in separate tests:
- How long can a completed export be downloaded?
- How long is a deleted project retained?
The first has a stated answer. The second does not.
This small fixture tests whether the assistant can answer from evidence and acknowledge an information gap.
It is a fictional policy, not a claim about any service.
3. Prepare a Claude-compatible route
For direct access, use an Anthropic API key and a supported model identifier.
For a gateway, verify native Messages support and preservation of citation fields. A gateway can return ordinary Claude text successfully while exposing a different subset of features.
TreeRouter’s model catalog is the starting point for checking model availability. Its integration documentation should determine the actual endpoint and authentication format you use.
Do not assume that an OpenAI-style chat response will preserve native Claude citation objects unchanged.
The feature must survive the entire route, including any SDK wrapper and application serializer.
4. Make a citation-enabled request
Install the Anthropic SDK:
python -m pip install anthropicSet ANTHROPIC_API_KEY for direct access.
The example below follows the native document-block format:
import json
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
max_retries=0,
timeout=60.0,
)
source = (
"Project export policy, revision 3. "
"Completed exports remain downloadable for 30 days. "
"This document does not specify how long deleted projects "
"are retained."
)
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=600,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": source,
},
"title": "Export policy revision 3",
"citations": {"enabled": True},
},
{
"type": "text",
"text": (
"How long can a completed export be downloaded? "
"Answer only from this document and cite the "
"supporting passage. State when information "
"is not provided."
),
},
],
}
],
)
if response.stop_reason != "end_turn":
raise RuntimeError(
f"Review incomplete response: {response.stop_reason}"
)
blocks = [
block.model_dump(mode="json")
for block in response.content
if block.type == "text"
]
print(json.dumps(blocks, ensure_ascii=False, indent=2))The output retains text blocks and their citation metadata.
Consult the official Claude citations guide for the current request and response contract.
The example uses direct access. Move it to a gateway only after confirming the required native route and feature support.
5. Preserve the response structure
A common integration mistake is keeping only a combined answer string.
That may be convenient for a simple chat interface, but it can discard the relationship between a text block and its supporting citation.
Store the original text blocks before creating a display version.
A useful application record includes:
- The question.
- The document version.
- The requested model.
- The response identifier.
- The original text blocks.
- Citation metadata attached to those blocks.
- The processing outcome.
Your application can then render clickable evidence without asking another model to reconstruct the citations.
6. Keep document identity under application control
The request may contain several documents.
Your application should map the returned document references to the exact source records supplied in that request.
Do not ask the model to invent public URLs for internal files. A generated link may point to the wrong version or expose a location the user cannot access.
Instead, construct the destination using your own document registry and permissions.
When a user opens a citation, verify access to that source. The fact that an answer contains a reference does not itself grant permission to view the underlying document.
Preserve document versions so an answer generated yesterday does not silently point to a rewritten policy today.
7. Handle absent and conflicting evidence
Test what happens when no document answers the question.
The assistant should explain that the supplied material does not establish an answer. It should not fill the gap using a plausible product policy.
Also test conflicting documents.
If one policy says 30 days and another says 60 days, provide an explicit precedence rule or ask the assistant to identify the disagreement. A newer-looking title alone may not be enough to establish which policy applies.
These decisions belong to your knowledge-management process.
Citations help users inspect the available evidence. They do not decide your company’s policy hierarchy.
8. Do not combine incompatible output requirements
Native citations and strict JSON output are different output contracts.
The current Claude documentation warns against combining citation-enabled documents with the strict structured-output format parameter.
For a document assistant, begin with cited text blocks.
If your application also needs a database record, design that transformation separately. Preserve the original cited response and validate any parsed fields.
Avoid an instruction such as “return only JSON” when the desired result is a natural-language answer with native citations. The instruction can work against the evidence format you are trying to retain.
9. Evaluate support at the claim level
An answer may contain several statements supported to different degrees.
Suppose the document says an export remains available for 30 days. The assistant adds that the export is automatically deleted on day 31.
The extra statement may sound reasonable, but the source did not establish it.
Review whether each meaningful claim is supported. Look for omitted conditions, unsupported recommendations, and language that turns an exception into a general rule.
Do not evaluate citation quality only by counting how many references appear.
A small number of relevant references can be more useful than citations attached indiscriminately to every sentence.
10. Connect citations to a usable interface
A citation interface should help the reader inspect evidence quickly.
Display a readable document title and a source preview where permissions allow it. Keep the cited answer segment visually connected to its source.
For long answers, avoid placing all references in an undifferentiated list at the bottom. Readers should be able to identify which passage supports which claim.
Also distinguish a document that cannot be opened from an answer that has no supporting reference. Those are different states requiring different messages.
The application should preserve useful evidence even when the presentation layer changes.
11. Verify gateway behavior before expanding usage
Run the same synthetic document through the selected route and inspect the raw response.
Check that citation metadata reaches your application and that your wrapper does not remove unfamiliar fields.
For TreeRouter, confirm the selected Claude model and native Messages capability before enabling this feature for a production knowledge assistant.
If you already use custom source IDs with other models, the existing DeepSeek and Qwen RAG citation guide provides a separate application-side pattern.
Treat these as different interfaces. Do not assume native Claude citation objects and your own source-ID schema are interchangeable.
Frequently asked questions
Does a citation prove the answer is correct?
No. It provides inspectable evidence. The generated claim still needs to match what the source establishes.
Can I flatten the answer into one string?
You can create a display string, but preserve the original blocks and citation metadata first.
Can I use any Claude gateway endpoint?
Verify native Messages and citation support for the selected route. Ordinary chat success is insufficient evidence.
Should I enable strict JSON output too?
Follow the current compatibility rules. Start with the native cited-text response and design any additional structured record separately.
Build a source-backed Claude workflow
Visit TreeRouter, confirm the Claude route and citation support, and register to test a small document workflow.
Start with a document containing one answerable question and one information gap. Preserve the raw response and verify that your interface can display the supporting evidence.
