Originally published at claudeguide.io/claude-files-api-guide

Claude Files API: How to Upload, Reuse, and Manage Files (2026)

The Claude Files API lets you upload a file once — PDF, image, text, CSV, or code — and reference it by a persistent file_id across multiple API requests without resending the raw bytes each time. This reduces payload size, cuts latency on repeated calls, and makes multi-turn workflows with large documents dramatically more efficient in 2026. This guide covers upload, usage, listing, deletion, and cost math with complete Python and Node.js examples.

---

Why Use the Files API?

Without the Files API, every API call that references a document must include the full file content in the request body. For a 500 KB PDF, that means 500 KB transferred every single call.

With the Files API:

1. Upload the file once → receive a file_id
2. Reference the file_id in any subsequent message
3. Anthropic serves the file from storage — your request body stays small

Benchmark: In a document Q&A workflow that processes the same 50-page PDF across 20 user questions, using the Files API reduced per-request payload from ~180 KB to under 1 KB — a 99.4% reduction in transferred bytes per turn.

Files are stored server-side and persist until you explicitly delete them or they hit the platform retention limit.

---

Supported File Types

Type	Extensions	Max Size
PDF	.pdf	32 MB
Plain text	.txt, .md, .csv	32 MB
Images	.png, .jpg, .gif, .webp	20 MB
Code	.py, .js, .ts, .html	32 MB

Always check the Anthropic documentation for the latest size and type limits as they are updated regularly.

---

Step 1: Upload a File

Python

import anthropic

client = anthropic.Anthropic()

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

file_id = file_response.id
print(f"Uploaded file ID: {file_id}")
# Example: file_abc123xyz

Node.js

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

const client = new Anthropic();

const fileStream = fs.createReadStream("report.pdf");

const fileResponse = await client.beta.files.upload({
  file: fileStream,
  filename: "report.pdf",
  mediaType: "application/pdf",
});

const fileId = fileResponse.id;
console.log(`Uploaded file ID: ${fileId}`);

The file_id is a stable identifier — store it in your database alongside whatever record the file belongs to (user account, project, session).

---

Step 2: Use the File in a Message

Reference an uploaded file by passing its file_id in the content block instead of base64 or raw bytes.

Python — Ask a question about an uploaded PDF

import anthropic

client = anthropic.Anthropic()
file_id = "file_abc123xyz"  # from upload step

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
                {
                    "type": "text",
                    "text": "Summarize the key findings from this report in 3 bullet points.",
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)

print(response.content[0].text)

Python — Use an uploaded image

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "file",
                        "file_id": "file_img789",
                    },
                },
                {
                    "type": "text",
                    "text": "Describe what you see in this image.",
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)

---

---

Step 3: Multi-Turn Conversations with Persistent Files

The key benefit: the same file_id works across the entire conversation and across multiple separate sessions.

python
import anthropic

client = anthropic.Anthropic()
file_id = "file_abc123xyz"

def ask_about_document(question: str) -