Skip to contents

Citations API

Source: vignettes/citations.qmd

Overview

The Citations API enables Claude to cite specific passages from documents, providing source attribution that eliminates hallucinations. When citations are enabled, Claude returns citation blocks that reference exact locations in your documents.

This vignette demonstrates how to use the Citations API with artclaude.

Citation Locations

Citations include precise location information:

  • char_location: Character offsets in plain text documents
  • page_location: Page numbers in PDF documents
  • content_block_location: Index in multi-block documents

Using Citations

Inline Documents

For local files, use claude_doc_cite() to create a document block with citations enabled:

library(artclaude)

chat <- claude_new()

# Upload document inline with citations
response <- chat$chat(
  claude_doc_cite("contract.pdf", title = "Service Agreement"),
  "What are the termination conditions? Cite the specific clauses."
)

# Response includes citation blocks with precise references

Uploaded Files

For files uploaded to Anthropic storage, you can enable citations on the content block:

# Upload file once
file <- claude_file_upload("report.pdf")

# Use with citations in multiple conversations
chat <- claude_new()
response <- chat$chat(
  claude_doc_cite(file$id, title = "Q4 Report"),
  "What were the revenue trends? Provide citations."
)

# Or use claude_file_content() with citations = TRUE
response <- chat$chat(
  claude_file_content(file$id, title = "Q4 Report", citations = TRUE),
  "Summarize the key findings with citations."
)

Citations with Context

Add context to help Claude understand the document:

chat <- claude_new()

response <- chat$chat(
  claude_doc_cite(
    "legal_brief.pdf",
    title = "Johnson v. Smith Brief",
    context = "This is a contract dispute case filed in 2024"
  ),
  "What precedents does the brief cite? Reference specific pages."
)

Citation Response Format

When citations are enabled, Claude’s response includes citation blocks:

{
  "type": "citation",
  "cited_text": "The exact text being cited...",
  "location": {
    "type": "page_location",
    "page_number": 3
  },
  "document_index": 0
}

Best Practices

When to Use Citations

Citations are ideal for:

  • Legal documents: Contracts, briefs, regulations
  • Research papers: Academic analysis with source attribution
  • Technical documentation: Precise references to specifications
  • Financial reports: Attribution for claims about metrics

Citation Quality

For best results:

  1. Use clear titles: Help Claude understand document context
  2. Provide context: Explain what the document contains
  3. Ask explicitly: Request citations in your prompt
  4. Structured queries: Ask for specific information with citations

Example: Contract Analysis 

chat <- claude_new()

# Analyze contract with citations
response <- chat$chat(
  claude_doc_cite(
    "vendor_contract.pdf",
    title = "Vendor Services Agreement",
    context = "3-year software services contract signed 2024-01"
  ),
  "Analyze the termination conditions. For each condition, cite the specific
   section and page number where it appears."
)

Example: Research Paper 

chat <- claude_new()

# Analyze research with citations
response <- chat$chat(
  claude_doc_cite(
    "study.pdf",
    title = "ML Performance Study 2024",
    context = "Comparative study of transformer architectures"
  ),
  "What performance improvements are claimed? Cite the specific results
   sections and page numbers."
)

Combining with Files API

Citations work seamlessly with the Files API for multi-conversation workflows:

# Upload once
contract <- claude_file_upload("contract.pdf")
addendum <- claude_file_upload("addendum.pdf")

# Use in multiple chats with citations
chat1 <- claude_new()
chat1$chat(
  claude_doc_cite(contract$id, title = "Original Contract"),
  "What are the payment terms? Cite specific clauses."
)

chat2 <- claude_new()
chat2$chat(
  claude_doc_cite(contract$id, title = "Original Contract"),
  claude_doc_cite(addendum$id, title = "Amendment #1"),
  "How does the addendum modify payment terms? Cite both documents."
)

# Clean up
claude_file_delete(contract$id)
claude_file_delete(addendum$id)

API Reference

For complete API documentation, see: