The default way to send Claude a document is inline: base64-encode it into the request body, every single time. That works, but it bloats payloads (the Messages API caps requests at 32 MB), wastes bandwidth, and forces every service that touches the document to carry a copy. The Files API — currently in beta — replaces that with an upload-once, reference-many model: POST /v1/files stores the file and returns an ID, and any later Messages request can point at it.
Uploading and referencing
Because the feature is in beta, requests need the header anthropic-beta: files-api-2025-04-14; the official SDKs add it automatically on the beta.files namespace, and Messages calls that reference a file pass it via betas.
from anthropic import AnthropicAWS # Claude Platform on AWS
client = AnthropicAWS()
f = client.beta.files.upload(file=open("employee-handbook.pdf", "rb"))
msg = client.beta.messages.create(
model="claude-sonnet-5", max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{"role": "user", "content": [
{"type": "document", "source": {"type": "file", "file_id": f.id}},
{"type": "text", "text": "Summarize the remote-work section."}]}],
)What a file becomes in a message depends on its type: PDFs and plain text map to document blocks, JPEG/PNG/GIF/WebP map to image blocks, and datasets or other formats go in as container_upload blocks for the code execution tool. Note that .docx and .xlsx are not supported in document blocks — convert them to plain text or PDF first — while .csv and .md can be uploaded as text/plain.
Limits and lifecycle
| Limit | Value |
|---|---|
| Max file size | 500 MB |
| Total storage per organization | 500 GB |
| API call rate during beta | ~100 requests/minute |
| Filename | 1–255 chars; no < > : " | ? * \ / or control characters |
Files persist until you delete them — there is no automatic expiry — and deletion is unrecoverable. They cannot be modified or renamed after upload; the supported pattern is upload-new, repoint, delete-old, which incidentally gives you clean versioning. Files are scoped to the workspace of the uploading API key, so a file uploaded by one workspace's key is invisible to another's. The full endpoint set covers upload, paginated listing, metadata, download, and delete — though files you upload are marked "downloadable": false; only files created by skills or the code execution tool can be downloaded back out.
Pricing is friendly: all Files API operations are free. You pay only when file content actually enters a Messages request, where it is billed as ordinary input tokens — which also means a file referenced in ten requests is billed ten times unless you pair it with prompt caching.
Platform availability — check before you architect
This is the feature's biggest enterprise caveat. The Files API is available (in beta) on the first-party Claude API and Claude Platform on AWS, and in beta on Microsoft Foundry for Hosted-on-Anthropic deployments only. It is not available on Amazon Bedrock or Google Vertex AI — on those platforms you keep sending documents inline as base64 (see the Bedrock workaround article). Teams also subject to Zero Data Retention agreements should note the Files API is documented as not ZDR-eligible; stored files are, by definition, retained. Confirm data-handling specifics with your provider.
Where to go next
See PDF support for what happens after the file reaches the model, and the code execution tool for the container_upload path. The feature matrix shows current platform status.