← Blog

Claude Files API: Upload Once, Reference Many Times

November 18, 2026

The Claude Files API lets you upload a document once and reference it by file ID across multiple requests instead of re-encoding on every call — the exam-tested pattern for scalable pipelines.

The Claude Files API lets you upload a document once and reference it by file ID across multiple requests instead of re-encoding it on every call. This cuts redundant token overhead on repeated documents, unlocks clean integration with the Message Batches API, and is the exam-tested pattern for high-volume document-processing pipelines.

What Is the Claude Files API and When Should You Use It Instead of Inline Encoding?

When you send a PDF or image to Claude inline, you base64-encode the file and embed the full binary data in every request. For a document you query exactly once, that is the simplest path. The problem arises when the same file powers many requests — each call re-encodes and re-transmits megabytes of content that Claude has already seen.

The Files API separates the upload step from the query step. You call the upload endpoint once, receive a persistent file_id, and reference that identifier in any number of subsequent Messages API calls in place of the full binary content. Claude resolves the file from storage; you transmit only a short string.

Three scenarios point clearly to the Files API over inline encoding:

  • Repeated queries against the same document. Uploading a PDF contract once and running ten analysis questions against it costs one upload versus ten re-encodings.
  • High-volume Batches workloads. When every item in a batch references the same report, the file ID eliminates duplicating megabytes of base64 across hundreds of requests.
  • Pipeline cleanliness. Separating document storage from request construction makes code easier to test, audit, and maintain across pipeline iterations.

For a document you will query once and discard, inline base64 remains simpler and correct. The Files API pays off when the same content crosses the API boundary more than once.

How Do You Upload a File and Receive a File ID?

The Files API lives under the beta namespace and requires the files-api-2025-04-14 beta header. The Python SDK sets this header automatically when you use client.beta.files.upload().

import anthropic

client = anthropic.Anthropic()

uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)

print(uploaded.id)           # file_011CNha...
print(uploaded.size_bytes)   # file size in bytes

The SDK also accepts a pathlib.Path object directly:

from pathlib import Path

uploaded = client.beta.files.upload(file=Path("contract.pdf"))

The response object contains id, filename, size_bytes, and mime_type. Store the id — it is the token you use in every subsequent request that needs this document.

How Do You Reference a File ID Inside a Request?

File IDs slot into the content block source field. For a PDF or text document, use type: "document" with source.type: "file":

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What are the key termination conditions?"},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "Service Agreement",
                "citations": {"enabled": True}
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)

For images, replace the block type with "image" and the same source.type: "file" pattern applies. One important constraint: the standard non-beta messages endpoint does not include a file-ID source variant — file references require client.beta.messages.create(). The beta header is required on every call that uses a file ID in a content block.

What File Types and Size Limits Does the Files API Support?

The Files API accepts the following content types:

  • PDF documents (application/pdf)
  • Images — JPEG, PNG, GIF, WebP
  • Plain text files

The per-file size limit is 500 MB. Total storage across all uploaded files is capped at 100 GB per organization.

Billing works on a split model: upload, list, and delete operations are free. Tokens that Claude reads from a file within a message are billed as standard input tokens at the rate for your chosen model. This means you are not charged for parking a document in storage — you pay only when it enters a prompt.

The Files API is a first-party Anthropic platform feature and is not available on Amazon Bedrock or Google Vertex AI.

How Does the Files API Pair With the Message Batches API?

The core pattern is straightforward: upload a document once, store its file ID, and reference that ID in every request across both single calls and batch submissions. The Message Batches API documentation notes that all Messages API features are supported, making file IDs a natural fit for large-scale document pipelines.

The design looks like this in practice:

  1. Upload the shared document and store the returned file_id.
  2. Build your batch, placing the same file_id in the document source of every request that needs it.
  3. Submit the batch. Each item references the uploaded file rather than carrying a fresh base64 copy.
  4. Poll for results as normal, then delete the file when the run is complete.

For a 200-request batch analyzing a large report, this avoids encoding and transmitting that document 200 times in a single batch payload. Combined with the Batches API's 50% cost reduction on token usage, the Files API + Batches combination is the standard architecture for large-scale document pipelines — and the pattern the Claude Certified Architect — Foundations exam treats as the benchmark for well-designed, cost-efficient document processing at scale.

How Do You List and Delete Files to Manage Storage?

Files persist until you explicitly delete them. There is no automatic expiry, so active management is required to stay within the 100 GB organizational cap.

List all uploaded files:

for f in client.beta.files.list():
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

The SDK auto-paginates; iterating the returned object walks all pages without manual cursor handling.

Retrieve metadata for one file:

info = client.beta.files.retrieve_metadata("file_011CNha...")
print(info.filename, info.mime_type)

Delete a file:

client.beta.files.delete("file_011CNha...")

In a production pipeline, the standard lifecycle is: upload at the start of a processing run, execute all requests that reference the file, then delete once the run is complete. This keeps storage tidy and prevents stale files from accumulating across pipeline iterations.

CCA-F Exam Checkpoint: Files API vs. Inline — The Decision Rule the Test Expects

The CCA-F exam frames document-processing architecture questions around when each encoding approach is appropriate. The decision rule the exam expects:

  • Inline base64 — correct for a document that appears in exactly one request and will not be reused.
  • Files API — correct when the same document appears across multiple requests, or when pairing with the Message Batches API for a high-volume pipeline.

Beyond the decision rule, expect the exam to test these specifics:

  • The Files API requires the files-api-2025-04-14 beta header.
  • File references require client.beta.messages.create() — the non-beta endpoint does not support the "file" source type.
  • The 500 MB per-file and 100 GB per-organization storage limits.
  • Upload and storage management operations are free; in-message token usage is billed at standard input rates.
  • The Files API is not available on Amazon Bedrock or Google Vertex AI.

The Files API + Batches combination is the architecture the exam uses as a reference design for scalable, cost-efficient document pipelines. Knowing when to reach for it — and understanding why inline encoding fails at scale — is the practical knowledge the certification tests.

This post explains how the Files API works conceptually. If you are working toward the Claude Certified Architect — Foundations certification, PlinthPrep offers practice questions on document-pipeline architecture, the Files API decision rule, and Batches integration — letting you test whether you have genuinely understood the material, not just read about it. PlinthPrep is an independent study resource, not affiliated with Anthropic. Visit plinthprep.com to see the exam-prep questions.

Frequently asked questions

What is the Claude Files API and when should I use it instead of inline base64?
The Claude Files API lets you upload a document once and reference it by a persistent file ID across multiple requests. Use it instead of inline base64 when the same document appears in more than one request — it eliminates repeated encoding and reduces overhead on every subsequent call.
What file types and size limits does the Claude Files API support?
The Claude Files API accepts PDF documents, images in JPEG, PNG, GIF, or WebP format, and plain text files. Each file can be up to 500 MB, and your organization's total storage cap is 100 GB. Upload and delete operations are free; tokens read from a file in a message are billed as standard input tokens.
How does the Claude Files API integrate with the Message Batches API for document pipelines?
Both APIs share the same file ID. Upload a document once to the Files API, then reference that file ID in every request inside a Batches payload. Claude resolves the file per batch item, so you avoid encoding and transmitting the same document across hundreds of requests in a single batch run.
What is the CCA-F exam decision rule for the Files API versus inline base64 encoding?
Use inline base64 for a document that appears in exactly one request and will not be reused. Use the Files API when the same document is referenced across multiple requests or in a high-volume Batches pipeline. The Files API is the exam-expected pattern whenever document reuse or batch scale is part of the design question.
How do you delete uploaded files from the Claude Files API?
Call the delete method on the files client, passing the file ID. Files persist until explicitly deleted and do not expire automatically. Deleting files you no longer need is important for staying within the 100 GB per-organization storage cap. The operation is free and takes effect immediately.

Share this post

Plinth Prep is an independent study resource and is not affiliated with, endorsed by, or sponsored by Anthropic. Practice material is written by Plinth Prep and does not reproduce real exam content.