Claude Files API Guide — Upload Once, Reference Anywhere in Your API Calls

# Install or update the Python SDK
pip install --upgrade anthropic
 
# Install or update the TypeScript SDK
npm install @anthropic-ai/sdk@latest

import anthropic
 
client = anthropic.Anthropic()
 
# Upload a PDF file
uploaded = client.beta.files.upload(
    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
 
print(f"File ID: {uploaded.id}")
# Example output: File ID: file_011CNha8iCJcU1wXNR6q4V8w
print(f"Filename: {uploaded.filename}")
# Example output: Filename: report.pdf
print(f"Size: {uploaded.size_bytes} bytes")
# Example output: Size: 1024000 bytes

import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
 
const anthropic = new Anthropic();
 
// Upload a PDF file
const uploaded = await anthropic.beta.files.upload({
  file: await toFile(
    fs.createReadStream("report.pdf"),
    undefined,
    { type: "application/pdf" }
  ),
  betas: ["files-api-2025-04-14"],
});
 
console.log(`File ID: ${uploaded.id}`);
// Example output: File ID: file_011CNha8iCJcU1wXNR6q4V8w

# Ask Claude to summarize the uploaded PDF
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Summarize the key takeaways from this document in 3 bullet points."
                },
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": uploaded.id,
                    },
                    "title": "Q4 Report",              # Optional
                    "citations": {"enabled": True},     # Enable citations
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
 
print(response.content[0].text)

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 2048,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Summarize the key takeaways from this document in 3 bullet points.",
        },
        {
          type: "document",
          source: {
            type: "file",
            file_id: uploaded.id,
          },
        },
      ],
    },
  ],
  betas: ["files-api-2025-04-14"],
});
 
console.log(response.content[0]);

# Upload an image
img = client.beta.files.upload(
    file=("screenshot.png", open("screenshot.png", "rb"), "image/png"),
)
 
# Ask Claude to analyze the image
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What UI improvements would you suggest for this screenshot?"},
                {
                    "type": "image",
                    "source": {
                        "type": "file",
                        "file_id": img.id,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)

# List all uploaded files
files = client.beta.files.list()
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")
 
# Get metadata for a specific file
metadata = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Created at: {metadata.created_at}")
 
# Delete a file
client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

import anthropic
from pathlib import Path
 
client = anthropic.Anthropic()
 
# Upload 12 months of reports in one go
file_ids = []
for month in range(1, 13):
    path = Path(f"reports/2025-{month:02d}.pdf")
    uploaded = client.beta.files.upload(
        file=(path.name, open(path, "rb"), "application/pdf"),
    )
    file_ids.append(uploaded.id)
    print(f"  Uploaded: {path.name} → {uploaded.id}")
 
# Run cross-document trend analysis
content_blocks = [
    {"type": "text", "text": "Analyze all 12 monthly reports below. Identify revenue trends and areas for improvement."}
]
for fid in file_ids:
    content_blocks.append({
        "type": "document",
        "source": {"type": "file", "file_id": fid},
    })
 
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": content_blocks}],
    betas=["files-api-2025-04-14"],
)
 
print(response.content[0].text)
# Cross-document analysis without re-uploading 12 PDFs each time

# Before — fragile, and can't prevent double-registration
def upload_naive(client, path):
    uploaded = client.beta.files.upload(
        file=(path.name, open(path, "rb"), "application/pdf"),
    )
    return uploaded.id

# After — retries + content-hash idempotency
import hashlib
import json
import time
from pathlib import Path
 
import anthropic
 
 
def file_sha256(path: Path) -> str:
    """Hash the file's contents (the key for dedup detection)."""
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1024 * 1024), b""):
            h.update(chunk)
    return h.hexdigest()
 
 
def upload_idempotent(
    client: anthropic.Anthropic,
    path: Path,
    media_type: str,
    ledger_path: Path = Path(".files_ledger.json"),
    max_retries: int = 4,
) -> str:
    """Upload each unique content hash once and record the file_id in a ledger."""
    ledger = json.loads(ledger_path.read_text()) if ledger_path.exists() else {}
    digest = file_sha256(path)
 
    # If we've already registered this exact content, reuse the file_id
    if digest in ledger:
        print(f"  reuse: {path.name} → {ledger[digest]}")
        return ledger[digest]
 
    last_error = None
    for attempt in range(1, max_retries + 1):
        try:
            uploaded = client.beta.files.upload(
                file=(path.name, open(path, "rb"), media_type),
            )
            ledger[digest] = uploaded.id
            ledger_path.write_text(json.dumps(ledger, ensure_ascii=False, indent=2))
            print(f"  new: {path.name} → {uploaded.id}")
            return uploaded.id
        except (anthropic.APIConnectionError, anthropic.RateLimitError) as e:
            last_error = e
            wait = min(2 ** attempt, 30)  # 2, 4, 8, 16 seconds (capped at 30)
            print(f"  retry {attempt}/{max_retries} (waiting {wait}s): {e!r}")
            time.sleep(wait)
        except anthropic.APIStatusError:
            # Errors that won't fix themselves (e.g. 413 too large) — stop immediately
            raise
 
    raise RuntimeError(f"Upload failed: {path.name}") from last_error