Building with the Claude Files API: Upload Once, Use Many Times

Every time you send a document to Claude via the standard messages API, you are sending the full file content in the request body — the entire base64-encoded image or the complete text of a PDF. If ten different users ask questions about the same 50-page policy document, that document is uploaded and transmitted ten separate times. At scale, this is wasteful in bandwidth, latency, and cost.

The Files API solves this. You upload a document once and receive a file ID. That ID can be referenced in any number of subsequent API requests without re-uploading the content. This is the right architecture for any application that processes the same documents repeatedly — knowledge bases, document Q&A systems, training material assistants, and compliance review tools.

What the Files API Is For

The Files API lets you:

Upload files once and reference them by ID in future requests
Store PDFs, images, plain text, CSV files, and other document types
List and manage your uploaded files via API
Delete files when they are no longer needed

Files uploaded via the Files API are stored on Anthropic's systems and associated with your API key. They persist until you delete them.

Files API vs Prompt Caching

The Files API and Prompt Caching are different optimisations for different scenarios. The Files API is for reusing the same uploaded file across many separate API calls — ideal when the document itself is the constant and the questions vary. Prompt Caching is for caching a long system prompt or context prefix that repeats across many requests in a session. Both can be used together in advanced architectures.

Uploading a File

python

import anthropic

client = anthropic.Anthropic()

# Upload a PDF document
with open("company-handbook.pdf", "rb") as f:
    response = client.beta.files.upload(
        file=("company-handbook.pdf", f, "application/pdf")
    )

file_id = response.id
print(f"File uploaded. ID: {file_id}")
# File uploaded. ID: file_011CNkBGpN7KDGmhXAMxdMpV

The upload request accepts:

PDF files: application/pdf
Plain text files: text/plain
Images: image/jpeg, image/png, image/gif, image/webp

Store the file_id — this is your permanent reference for the uploaded content across any number of future requests.

Using a Stored File in a Request

Once a file is uploaded, reference it by ID in the messages content block using the document content type:

python

import anthropic

client = anthropic.Anthropic()

# file_id obtained from previous upload
file_id = "file_011CNkBGpN7KDGmhXAMxdMpV"

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id
                    },
                    "title": "Company Handbook",
                    "context": "This is the company employee handbook."
                },
                {
                    "type": "text",
                    "text": "What is the company's policy on remote work and flexible hours?"
                }
            ]
        }
    ],
    betas=["files-api-2025-04-14"]
)

print(response.content[0].text)

The beta header enables the Files API. Note the betas=["files-api-2025-04-14"] parameter — this is required for the Files API and uses the beta client (client.beta.messages.create).

Listing and Managing Files

List Uploaded Files

python

# List all uploaded files for your API key
files = client.beta.files.list()

for file in files.data:
    print(f"ID: {file.id}")
    print(f"Name: {file.filename}")
    print(f"Size: {file.size} bytes")
    print(f"Created: {file.created_at}")
    print("---")

Get File Metadata

python

# Retrieve metadata for a specific file
file_info = client.beta.files.retrieve_metadata(file_id)
print(f"File: {file_info.filename}, Size: {file_info.size}")

Delete a File

python

# Delete a file when it is no longer needed
client.beta.files.delete(file_id)
print(f"File {file_id} deleted.")

Building a Document Q&A System

Here is a practical pattern for a document question-answering system that uses the Files API to serve multiple user questions from a single uploaded document:

python

import anthropic

client = anthropic.Anthropic()

class DocumentQA:
    def __init__(self, pdf_path: str, document_title: str):
        # Upload the document once during initialisation
        with open(pdf_path, "rb") as f:
            upload_response = client.beta.files.upload(
                file=(pdf_path, f, "application/pdf")
            )
        
        self.file_id = upload_response.id
        self.document_title = document_title
        print(f"Document uploaded: {self.file_id}")
    
    def ask(self, question: str) -> str:
        """Answer a question about the uploaded document."""
        response = client.beta.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            messages=[
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "document",
                            "source": {
                                "type": "file",
                                "file_id": self.file_id
                            },
                            "title": self.document_title
                        },
                        {
                            "type": "text",
                            "text": question
                        }
                    ]
                }
            ],
            betas=["files-api-2025-04-14"]
        )
        
        return response.content[0].text
    
    def cleanup(self):
        """Delete the file when finished."""
        client.beta.files.delete(self.file_id)


# Usage
qa = DocumentQA("annual-report-2025.pdf", "Annual Report 2025")

# Ask multiple questions — document is uploaded only once
print(qa.ask("What was the total revenue for Q3 2025?"))
print(qa.ask("Which regions showed the highest growth?"))
print(qa.ask("What are the key risks mentioned in the report?"))

# Clean up
qa.cleanup()

Persist file_ids in Your Database

For production applications, store file_ids in your application database alongside metadata about what document they represent, when they were uploaded, and which users have access to them. This lets you avoid redundant uploads when users access the same document, maintain an inventory of your stored files, and implement cleanup routines to delete files that have not been accessed in a set period.

Multi-Document Workflows

The Files API supports including multiple document files in a single request — useful for comparative analysis or synthesis across multiple sources:

python

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": contract_v1_id},
                    "title": "Contract Version 1 (Current)"
                },
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": contract_v2_id},
                    "title": "Contract Version 2 (Proposed)"
                },
                {
                    "type": "text",
                    "text": "Compare these two versions of the contract. What are the key differences in the liability clauses, payment terms, and termination conditions?"
                }
            ]
        }
    ],
    betas=["files-api-2025-04-14"]
)

Pricing and Storage Limits

File storage is associated with your API key and counts against your usage
Files are charged at a per-byte storage rate — check the Anthropic pricing page for current rates
When a file is used in a request, the content contributes to your input token count for that request
The key cost benefit: even if you reference a file ID many times, you avoid the data transfer overhead of re-uploading base64 content on every request

Delete Unused Files Promptly

Files persist until you explicitly delete them. Implement a cleanup routine in your application that deletes files that are no longer needed — for example, files created for a single-session user interaction should be deleted when that session ends. Accumulating thousands of unused files will add unnecessary storage costs and make file management harder.

Summary

The Files API is the right architecture for any Claude application that works with documents repeatedly. Upload once, reference by ID, and reuse across as many requests as needed.

Key practices:

Use client.beta.files.upload with the correct MIME type for your file
Include betas=["files-api-2025-04-14"] in all requests that reference uploaded files
Store file_ids in your database to avoid redundant uploads
Implement cleanup routines to delete files that are no longer needed
Use the document content type with a file source in your messages content blocks

With the Files API completed, we have now covered all the major tools in Claude's capability set. Time for a knowledge check: Knowledge Check: Claude Tools & Capabilities Quiz.

This post is part of the Anthropic AI Tutorial Series. Previous post: Claude Computer Use: Let Claude Control a Desktop.