Citations in the Claude API help connect a fragment of the response to a location in the source you provided. For an employee to actually open the right evidence, the application needs to store not only the response text, but also the mapping between documents, file versions, and citation coordinates. A nicely formatted link without that connection can lead to a different document.
This FAQ is for the developer of a corporate assistant and the owner of a knowledge base. It answers questions about displaying sources in the interface: where to get the page from, how to distinguish formats, and what to preserve between requests. It covers working with provided documents in the Messages API, not the Claude user chat interface or the overall RAG architecture.
The official documentation was checked on November 1, 2026. Claude API calls, file uploads, and interface behavior were not performed. The page ranges and application diagram below were prepared manually for explanation; these are not model outputs and not a verified SDK example.
Contents
- Is it enough to say, "answer with source links"?
- How do you tell which PDF pages are included in a citation?
- Why does a text document use coordinates instead of a page number?
- Why can the model read a scan, but no citation appears for it?
- Can document_index be used as a permanent file ID?
- Can you get strict JSON and embedded citations at the same time?
- What changes if the document is uploaded through the Files API?
Is it enough to say, "answer with source links"?
For embedded citations, documents are sent with citations.enabled=true; in a single request, this setting must be enabled for all documents or disabled for all of them. Citations Guide.
A normal request in the prompt and a function setting are different parts of the integration. The developer needs a clear answer to the question: did the link come as API metadata, or was it written by the model inside regular text?
For example, an assistant answers an employee about the approval timeline for a request. For the interface, it is useful to store two linked entities: the statement itself and the description of the source location. Then the designer can show a neat "Open source" button, and the button handler can find the right file. If you keep only the finished response string, that connection will have to be reconstructed later.
This is a design decision for the application. It does not imply that every sentence will automatically receive a separate sufficient citation.
How do you tell which PDF pages are included in a citation?
For PDF start_page_number starts at 1, and end_page_number is not included in the range. Examples:
| Start | End | Pages to open |
|---|---|---|
| 3 | 4 | Only 3 |
| 3 | 5 | 3 and 4 |
The indexing rule is described in the citation documentation.
An off-by-one error is especially noticeable in the viewer: the user clicks the link, sees an adjacent page, and decides the assistant made up the source. That's why the conversion from a range into a button label needs to be agreed with the PDF viewer developer.
The page number in the file and the printed number at the bottom of the page may differ because of a cover page or appendices. The PDF support documentation recommends relying on numbers in the PDF viewer. PDF handling rules.
In the interface, you can explicitly label it as a "file page," and show the printed page number separately if the application can actually determine it. Do not automatically calculate a cover-page offset for the entire archive: different documents can have different structures.
Why does a text document use coordinates instead of a page number?
The coordinate format depends on the source:
| Source | Citation coordinate |
|---|---|
| PDF with text | Page range, starting at 1 |
| Plain text | Character range, starting at 0 |
| Custom content | Block range, starting at 0 |
For characters and blocks, the end boundary is also not included. Coordinate types in the API.
Do not try to open every source using the universal "page" field. For a text-based policy document, the application needs a view of the text fragment; for PDF, a page view; for preassembled blocks, its own link to the original record.
If you converted a PDF to text, keep the connection between the text and the original before sending the request. Otherwise, having a character coordinate will not by itself restore the original page number. The workflow for preparing different documents is covered in a comparison of PDF parsers for RAG.
Why can the model read a scan, but no citation appears for it?
Image understanding and text citation are different capabilities. Embedded citations do not support images; a PDF scan without extractable text is not a citable source. Citations limitations.
At the same time, the PDF support mechanism analyzes both text and page images. So the ability to answer a question about an image does not prove there is a text citation for that same object. How Claude processes PDF.
For an operational archive, first determine exactly what the employee needs to open. If a fragment of recognized text is needed, you will need to prepare a text layer and verify that it matches the scan. If the evidence is a diagram or a caption in an image, the interface may need a separate page display with an explanation of where it came from.
Do not replace a missing citation with a manually written "p. 7" formatted to look the same as a machine-generated coordinate. Such a label is only acceptable as separately verified application markup with a clear origin.
Can document_index be used as a permanent file ID?
No: document_index is the document's position in the provided set, starting at 0, not an ID in your database. Document link reference guide.
Imagine two requests. In the first, you send the policy and its appendix; in the second, the appendix and the policy. The same positional index now points to different sources. This is an example that shows why you must preserve the composition of a specific request.
The recommended approach is to store your own mapping alongside the result: "document position in this request → internal ID → version → original available to the user." The values and field names are up to your application; this is not a new required Claude API schema.
For a long-lived link, the title "Procurement Policy" is not enough. A company may have multiple revisions and documents with the same name. You need to open the version that was used in the response, and show the validation of that version separately.
Can you get strict JSON and embedded citations at the same time?
Combining quoted citations with strict JSON via output_config.format is incompatible: the documentation indicates a 400 error. This is a limitation of a specific output mode, not a ban on storing processing results in JSON. Structured outputs compatibility.
The guide recommends a different approach: request fields in a text response with quotes and then parse the result in your own code. You still need to verify the presence of both the value and the quote for each field. Section on structured data with quotes.
For example, your application could store a manually assembled record like this:
{
"field": "approval_period",
"value": "needs to be clarified based on the current version",
"source_record": "purchasing-policy",
"source_revision": "training-example",
"review_status": "needs_review"
}This is a training schema for an internal result, not a Claude response, API parameter, or real policy. The evidence link should be stored alongside it according to your application's rules. If the processor did not find a quote or a clear value, it is better to save an explicit parsing status than to fill the field with a plausible guess.
What changes if the document is uploaded through the Files API?
The Files API lets you upload a file and reference it via file_id. An uploaded file cannot be edited in place: for a new version, you need to upload a new file. The documentation also warns that access to uploads is determined by the workspace, not by an individual conversation or end user. Files API.
For an enterprise assistant, this is a reason to separate two decisions. First: which object is stored with the API provider. Second: which employee in your application has permission to open the source document. A citation in the response alone does not define the second rule.
Keep your own mapping table of versions and files. When replacing a document, update it intentionally while preserving the ability to explain older answers. Do not promise users that deleting a card in your database instantly deletes all related objects in other systems: that is a separate operation with a separate result.
Why not save only the combined response text?
The Messages API returns message content as a set of blocks. When processing a response, take the structure into account, not just the visually merged string. Create a Message reference.
The suggested flow for the interface is to save the original result representation first, then separately assemble the text for display and the list of links to sources. This makes it possible to fix how links are displayed without rewriting the answer.
The developer should define what happens when there are multiple sources for one claim, a repeated citation, or an unavailable original. The button can stay in place with an honest access message; it should not silently open a different file with a similar name.
If the application works with a response stream, the rules for message completion and partial data are covered in a separate FAQ on Claude API streaming responses.
Does a working link prove the entire response is correct?
No. A working link lets you verify a specific source. For the user, two separate questions remain: does the excerpt support the claim, and does the rule apply to their situation?
Imagine a valid deadline is given for one department, while the question was asked about another. Technically, the page link may work perfectly, but the answer still does not fit the employee. This is a fictional example of checking the scope of a rule, not a Claude error.
A deeper question—how significantly a material fact influenced the final decision—is covered in the article on AI document analysis. Here the task is narrower: make the origin of the answer accessible and understandable so that such a check is even possible.
How Vladimir Lomtev's AI studio helps show sources in an AI assistant
Vladimir Lomtev's AI studio can prepare documents and their revisions for the knowledge base, design the interface that links an answer to its source, integrate search with the enterprise assistant, and verify that responses match the source materials. This concerns the structure of the entire knowledge base, not just the design of a citation button.
The first step is to choose one set of documents, define the owner, the permitted user group, and the criterion: the employee opens the source for the needed version and can verify the claim. Discuss the project.
Bottom line: store the citation together with the document and its version
To display sources reliably, link the response, coordinate type, request composition, and original version. Distinguish the PDF page, text characters, and blocks, preserve the structure of the result, and explicitly mark the absence of evidence. Then the citation becomes a working link to the source, not just persuasive formatting for the answer.
