Upload Once, Reference Everywhere: Stop Re-uploading PDFs on Every Claude API Call

The Anthropic Files API lets you upload a PDF or image once, receive a file_id, and reference it in any number of messages.create calls — stop re-uploading the same document bytes on every request.

If you send the same document to Claude repeatedly — a policy PDF, a user's contract, a large codebase snapshot — you're paying upload bandwidth and encoding time on every call. The Files API separates the upload from the inference step.

The pattern

import anthropic

client = anthropic.Anthropic()

# Step 1: Upload once
uploaded = client.beta.files.upload(
    file=("policy.pdf", open("policy.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id  # e.g. "file_011CNha8iCJcU1wXNR6q4V8w"

# Step 2: Reference by ID on every call — no re-upload
def ask(question: str) -> str:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        betas=["files-api-2025-04-14"],       # required beta header
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": question},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_id},
                    "citations": {"enabled": True},   # cite specific passages
                },
            ],
        }],
    )
    return response.content[0].text

print(ask("What is the refund window?"))
print(ask("Are there exceptions for enterprise customers?"))

For images, change "type": "document" to "type": "image" and set the MIME type to image/png, image/jpeg, image/gif, or image/webp.

When to use it

Scenario	Approach
Same document referenced ≥2 times	Files API: upload once, reuse by file_id
One-off single call	Inline the content directly — no upload step needed
Batch API + same doc on every item	Upload once, pass file_id in every batch item

Files persist until you delete them (500 GB org quota). Clean up when done:

client.beta.files.delete(file_id)

# List all uploaded files
files = client.beta.files.list()

The beta header

The SDK adds anthropic-beta: files-api-2025-04-14 automatically when you use client.beta.files.* for file operations. For messages.create calls that reference a file_id, pass betas=["files-api-2025-04-14"] explicitly (shown above).

Available on the Claude API and Claude Platform on AWS. Not yet on Amazon Bedrock or Google Cloud.

Sources: Files API — Claude Platform Docs