Files API

The Files API lets you upload a file to the Claude API once, with POST /v1/files, and then point to it by its file_id in any later request instead of sending the bytes again (Files API). It takes PDFs and plain text (read as documents), JPEG, PNG, GIF and WebP images, and other files such as CSV datasets for the code execution tool, up to 500 MB per file and 1 TB per organization. Uploading and storing are free; the file's content is billed as input tokens each time a request uses it. It also works the other way: charts, spreadsheets and documents that Claude creates with code execution or Skills are downloaded through it. The Files API left beta on Aug 19, 2026 and no longer needs a beta header.

Quick facts

Source: Files API, Anthropic docs, read Nov 6, 2026.

How do you upload a file to the Claude API?

With curl, from Anthropic's docs:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -F "file=@/path/to/document.pdf"

Or in Python:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
print(uploaded.id)  # file_011CNha8iCJcU1wXNR6q4V8w

The reply describes the stored file: its id, filename, mime_type, size_bytes, created_at, expires_at, and downloadable, which is false for anything you upload. The ant CLI does the same with ant files upload --file <path>.

Using a file in a message

Pass the file_id in a content block of a Messages API request:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Please summarize this document for me."},
    {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
  ]
}

The block depends on the file (Files API):

Word and Excel files are not read as documents: convert a .docx or .xlsx to text, or a .docx with images to PDF, or hand the file to the code execution tool as a container_upload to analyze there. PDF pages typically cost 1,500 to 3,000 tokens each, since Claude reads both the text and an image of every page; see Image and PDF Uploads for the limits.

Listing, downloading and deleting

Source: Files API, Anthropic docs, read Nov 6, 2026.

Only files Claude created can be downloaded, from Skills or the code execution tool; downloading your own upload returns a 400 error. Generated images, video and audio downloaded from the Claude API carry signed C2PA Content Credentials. A file cannot be renamed or edited after upload: upload a new one and delete the old. A deleted file cannot be recovered.

Expiry and retention

Without expires_in_seconds, a file stays until you delete it. With it, set once at upload to anything between 3,600 seconds (1 hour) and 7,776,000 (90 days), the content stops being usable at expires_at: downloads return 404 and requests that cite the file fail before inference, while its metadata remains listed for up to 30 more days. Anthropic notes that expiry is not a guaranteed-deletion control, since content may be kept a little longer for safety review. Because files are stored until deleted, the Files API falls outside zero data retention (API and data retention). With the Compliance API on, uploads, downloads and deletions appear in the audit Activity Feed.

Who can see an uploaded file?

Every API key with access to the workspace. Files are not tied to an end user, conversation or session, and Anthropic's docs warn never to accept file_id values from end users, since a user who supplied someone else's id could read that person's file. A multi-tenant app should keep its own map of users to files, and Anthropic suggests one workspace per tenant for hard isolation; an organization can have up to 100 workspaces.

Where it works

The Files API works with every current model on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry hosted on Anthropic; it is not offered on Amazon Bedrock or Google's own Claude service (Claude on Cloud Platforms). In Managed Agents, uploaded files can be mounted read-only in a session's sandbox, and files an agent writes to its outputs folder are downloaded through the same API.

Common errors

• 404: the file_id does not exist or belongs to another workspace.
• 400: the file type does not match the block (an image in a document block), the file is larger than the model's context window, the name breaks the 1 to 255 character rule, a download was asked of an upload, or the organization's 1 TB is full.
• 413: the file is over 500 MB.

Source: Files API, Anthropic docs, read Nov 6, 2026.

Frequently asked questions

Is the Claude Files API free? Storing files in the Claude Files API costs nothing, and upload, list, download and delete calls are free; the file's content is billed as input tokens each time a Messages request uses it.

What is the maximum file size for the Claude Files API? Each file can be up to 500 MB, and an organization can store up to 1 TB in total. A file used in a request must still fit in the Claude model's context window.

Can Claude read Word or Excel files through the API? Not as documents: the Claude API reads PDFs and plain text in document blocks. Convert .docx or .xlsx to text or PDF first, or give the file to the code execution tool to open with Python.

How long are files kept in the Claude Files API? Until you delete them, unless you set expires_in_seconds at upload (1 hour to 90 days). Expired files stop working at once, and their metadata disappears within 30 days.

Do I still need the files-api beta header? No. The Claude Files API has been out of beta since Aug 19, 2026; requests that still send files-api-2025-04-14 keep working but receive the older beta response shapes.

Sources

• Files API, Anthropic docs, read Nov 6, 2026
• PDF support, Anthropic docs, read Nov 6, 2026
• API and data retention, Anthropic docs, read Nov 6, 2026
• Release notes, Anthropic docs, read Nov 6, 2026