Claude Files API — Upload, Reference, and Manage Files

How to use Anthropic's Files API to upload documents, images, and PDFs once and reference them across multiple Claude API requests. Python and TypeScript examples.

Anthropic's Files API lets you upload a file once and reference it by ID in multiple API requests. Instead of re-sending a large PDF or image as base64 on every call, you upload it once, get a file_id, and attach it by reference. This reduces bandwidth and, combined with prompt caching, cuts cost dramatically for repeated large-document workflows.

Supported file types

Total storage per workspace: 100 GB. Files expire after 30 days of non-use.

Upload a file (Python)

import anthropic

client = anthropic.Anthropic()

with open("contract.pdf", "rb") as f:
    response = client.beta.files.upload(
        file=("contract.pdf", f, "application/pdf")
    )

file_id = response.id
print(f"Uploaded: {file_id}")  # file_01ABC...

Reference the file in a message

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "file",
                    "file_id": file_id
                }
            },
            {
                "type": "text",
                "text": "Summarise the key obligations in this contract."
            }
        ]
    }]
)
print(message.content[0].text)

TypeScript example

import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";

const client = new Anthropic();

const upload = await client.beta.files.upload({
    file: new File([fs.readFileSync("report.pdf")], "report.pdf", { type: "application/pdf" })
});

const msg = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [{
        role: "user",
        content: [
            { type: "document", source: { type: "file", file_id: upload.id } },
            { type: "text", text: "What are the main findings?" }
        ]
    }]
});
console.log(msg.content[0].text);

List and delete files

# List all uploaded files
files = client.beta.files.list()
for f in files.data:
    print(f.id, f.filename, f.size)

# Delete a file
client.beta.files.delete(file_id)

Cost comparison: Files API vs base64 inline

When to use the Files API

• The same document is referenced in 10+ separate API calls (contract review, RAG re-ranking).
• Files are large (>1 MB) and bandwidth is a constraint in your infrastructure.
• Multiple team members or services need to reference the same canonical file without re-uploading.
• You're building a document Q&A product where users upload once and ask multiple questions.

Estimate total cost including Files API usage with the Claude Cost Calculator. For document-heavy pipelines, the Prompt-Pricing Recommender helps choose between Haiku, Sonnet, and Opus for document analysis tasks.

Frequently asked questions

Free tools

Related