The Files API (currently in beta, header anthropic-beta: files-api-2025-04-14) changes the document workflow model: instead of re-sending a PDF as base64 with every request, you upload it once to Anthropic's storage, receive a file_id, and reference that ID in Messages requests from then on. For document-heavy retrieval workloads that is a real convenience — but it also means your documents now persist on Anthropic's side, which is exactly the property a security review needs to examine.
Scoping: the workspace is the boundary
Files are scoped to the workspace of the API key that uploaded them. Any API key in the same workspace can reference the file; keys in other workspaces cannot. That makes workspace layout a security decision: if you separate tenants, environments, or departments by workspace, their file stores are separated too. If everything shares one workspace, every key in it can read every uploaded document. Treat this the way you would an object-storage bucket policy — decide the isolation boundary first, then upload.
Immutability and non-recoverability
Three lifecycle rules are absolute:
- Files are immutable after upload. There is no in-place update — a corrected document is a new upload with a new
file_id, and your application must repoint references itself. - Files persist until deleted. There is no automatic expiry; cleanup is your job.
- Deleted files cannot be recovered. Deletion is final, which cuts both ways: good for data-minimization commitments, unforgiving for operational mistakes.
One asymmetry surprises people: files you upload are not downloadable afterwards (downloadable: false) — download exists only for files that Claude generates via skills or the code execution tool. The Files API is a reference store, not a backup: keep your own system of record.
The ZDR trade-off
Zero Data Retention (ZDR) is the arrangement in which Anthropic does not retain request data after processing. Here is the trade-off the Files API forces: the Files API is not eligible for ZDR — its data follows the standard retention policy, which is the whole point of a persistent file store. Meanwhile the alternative document inputs are ZDR-eligible: citations, PDF support via inline base64, and search-result content blocks all qualify.
Storage limits and how errors surface
Two quotas apply: 500 MB maximum per file, and 500 GB total per organization. They fail differently — an oversized file returns HTTP 413, while an upload that would exceed the organization-wide cap returns HTTP 400. Because the org limit is shared across all workspaces and there is no auto-expiry, a busy pipeline that never deletes will eventually hit 400s in production; build deletion into the pipeline, not into an incident response. File operations themselves (upload, list, metadata, delete) are free — you pay normal input-token prices only when file content is used in a Messages request — and a beta rate limit of roughly 100 file-related calls per minute applies.
Platform availability
Per Anthropic's documentation: the Files API is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry — where it requires a Hosted on Anthropic deployment (Hosted-on-Azure deployments return an error) — and is not currently available on Amazon Bedrock or Google Cloud. On Bedrock and Vertex, documents travel inline with each request, so the retention questions above largely don't arise there; your documents pass through rather than persist. As always with compliance-adjacent decisions, this inherits your provider's posture — confirm specifics with your provider.
Where to go next
For the request-side mechanics (content-block mapping, file_id references, citations on file-backed documents), see the Files API overview. For weighing inline documents plus caching against persistent uploads, citations billing mechanics covers the cost half of the trade.