Skip to contents

Files API and Citations

Source: vignettes/files-citations.qmd

Overview

This vignette demonstrates the Files API and Citations features in artclaude:

  1. Files API: Upload files once, reference across multiple conversations
  2. Citations API: Get precise source attribution from documents

Files API

Uploading Files

Upload files to Anthropic’s storage for persistent use:

library(artclaude)

# Upload a PDF
file <- claude_file_upload("report.pdf")
file$id # "file_abc123..."
file$filename # "report.pdf"
file$size_bytes # File size in bytes
file$mime_type # "application/pdf"

Supported file types: - PDFs: application/pdf - Images: image/jpeg, image/png, image/gif, image/webp - Plain text: text/plain

Limits: - Max file size: 500 MB - Total storage: 100 GB per organization

Using Files in Conversations

Reference uploaded files across multiple conversations:

# First conversation
chat1 <- claude_new()
chat1$chat(claude_file_content(file$id), "Summarize this report")

# Second conversation - same file
chat2 <- claude_new()
chat2$chat(claude_file_content(file$id), "Extract key metrics")

# With title and context
chat3 <- claude_new()
chat3$chat(
  claude_file_content(file$id,
    title = "Q4 Report",
    context = "Financial results for Q4 2024"
  ),
  "What were the revenue trends?"
)

Managing Files 

# List all uploaded files
files <- claude_file_list()
sapply(files, function(f) f$filename)

# Get metadata for specific file
metadata <- claude_file_get(file$id)
metadata$mime_type

# Download file content
content <- claude_file_download(file$id)
writeBin(content, "downloaded_report.pdf")

# Delete file when done
claude_file_delete(file$id)

Citations API

Enabling Citations

Get precise source attribution from documents:

# With uploaded file
file <- claude_file_upload("contract.pdf")
chat <- claude_new()

response <- chat$chat(
  claude_file_content(file$id, citations = TRUE),
  "What are the termination conditions? Cite specific clauses."
)

# Or use claude_doc_cite() convenience function
response <- chat$chat(
  claude_doc_cite(file$id, title = "Service Agreement"),
  "What are the payment terms? Cite specific sections."
)

Inline Documents with Citations

For local files without uploading:

chat <- claude_new()

# Inline document with citations
response <- chat$chat(
  claude_doc_cite("legal_brief.pdf",
    title = "Johnson v. Smith Brief",
    context = "Contract dispute case filed in 2024"
  ),
  "What precedents are cited? Reference specific pages."
)

Citation Response Format

Citations include precise location information:

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

Location types: - char_location: Character offsets in plain text - page_location: Page numbers in PDFs - content_block_location: Index in multi-block documents

Multi-Document Citations

Cite across multiple documents:

contract <- claude_file_upload("contract.pdf")
addendum <- claude_file_upload("addendum.pdf")

chat <- claude_new()
chat$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."
)

Combined Workflow

Typical workflow combining Files API and Citations:

library(artclaude)

# 1. Upload documents
contract <- claude_file_upload("vendor_contract.pdf")
sow <- claude_file_upload("statement_of_work.pdf")
invoice <- claude_file_upload("invoice_q4.pdf")

# 2. Analyze with citations
chat <- claude_new()

# Contract analysis
chat$chat(
  claude_doc_cite(contract$id, title = "Vendor Contract"),
  "List all deliverables. Cite specific sections."
)

# Cross-document analysis
chat$chat(
  claude_doc_cite(contract$id, title = "Contract"),
  claude_doc_cite(sow$id, title = "Statement of Work"),
  claude_doc_cite(invoice$id, title = "Q4 Invoice"),
  "Verify that the invoice aligns with contract terms and SOW deliverables.
   Cite specific sections from each document."
)

# 3. Clean up
claude_file_delete(contract$id)
claude_file_delete(sow$id)
claude_file_delete(invoice$id)

Best Practices

When to Upload vs Inline

Upload files when: - Using same file across multiple conversations - File will be referenced repeatedly - Working with team (shared file IDs)

Use inline when: - One-time analysis - File is small - Don’t want persistent storage

Citation Quality

For best citation 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
chat <- claude_new()

response <- chat$chat(
  claude_doc_cite(
    "contract.pdf",
    title = "Software License Agreement",
    context = "Enterprise software license signed 2024-03-15"
  ),
  "Analyze the liability limitations. For each limitation, cite the exact
   section number and page where it appears."
)

API References