Claude Files API: Expiration, Storage, Access, and Deletion

Quick answer

The Claude Files API stores an input once and lets later Messages API requests reference its file ID. It also provides the download path for files created by Skills or code execution. Current documentation lists a 500 MB per-file limit and 1 TB total storage per organization.

Files are scoped to the workspace, not the individual API key. They persist until deleted or until an upload-time expiration is reached. Set expires_in_seconds when the business purpose has a known end, never treat a file ID as proof of caller authorization, and test expired and deleted references.

File lifecycle at a glance

Stage	Decision	Evidence to keep
Upload	Is the file required, allowed, and correctly classified?	Owner, source, hash, purpose, expiry
Reference	May this caller use this workspace file for this task?	Caller, file ID, request, policy result
Process	Is the content compatible with the chosen block or tool?	Type, size, model/tool path, result
Download	Is this an API-generated artifact and safe to deliver?	Metadata, scan, review, destination
Expire	Does an automatic end match the business purpose?	expires_at, cleanup owner, fallback
Delete	Are consumers reconciled and recovery expectations clear?	Deletion event, affected references

Workspace access is the critical boundary

Any API key in the same workspace can reference uploaded files. Do not accept an arbitrary file ID from an untrusted caller and pass it into a Messages request. Resolve the caller’s identity and resource permission in your own application, then compare it with a server-side record of the file’s owner, purpose, and allowed use.

Keep tenants with incompatible trust or retention requirements out of the same broad workspace. Rotate or revoke keys when their role changes, but remember that key rotation alone does not delete stored files.

Expiration behavior

Set expires_in_seconds at upload to a value from one hour through 90 days. The resulting expires_at is fixed and cannot be changed. To extend a lifecycle, upload a new file under a new review and delete the old file when its consumers are reconciled.

After expiration, content download returns 404 and a Messages request referencing the file fails before inference. Metadata can remain readable and the expired item can remain in list responses for up to 30 days. Compare expires_at with the current time rather than treating list membership as usable content.

Delete expired metadata explicitly when operational inventory must stop showing it. Build failure handling for references that expire between scheduling and execution.

Uploads and generated downloads differ

Files you upload are not downloadable through the Files API. Files created by Agent Skills or code execution can be downloaded, and their file IDs appear in code-execution result content. Keep the original upload in your source system if you need to retrieve it later.

Validate generated downloads before delivery. Check the reported filename and MIME type, scan or render the artifact where appropriate, and confirm that it does not contain source secrets, hidden content, unsafe formulas, external links, or unsupported claims.

The Skills versioning guide explains how to bind a generated artifact to the exact Skill version that created it.

Deletion, retention, and audit

Deleted files cannot be recovered and become inaccessible through the API shortly after deletion, although active Messages calls and tool uses may still hold references. Do not promise instantaneous erasure from every processing context. Align user-facing retention language with Anthropic’s current data-retention policy and your own system copies, logs, backups, and downstream exports.

Organizations with the Compliance API enabled can receive activity events for uploads, generated-content downloads, and deletions. Listing and metadata retrieval are not recorded, and operations that occurred before audit was enabled cannot be reconstructed later. Enable the required audit surface before relying on it as evidence.

A safe implementation checklist

1. Keep file metadata in an application table with tenant, owner, purpose, classification, hash, and expiry.
2. Authorize every reference server-side; never trust possession of a file ID.
3. Use the shortest useful expiration and test pre-inference expiration failures.
4. Reconcile scheduled jobs before deletion or replacement.
5. Validate generated files before users download or share them.
6. Monitor organization storage and clean superseded files.
7. Test key revocation, tenant isolation, expired metadata, deletion, and downstream cleanup.

Review the Claude Platform GA overview before combining stored documents with web or desktop actions, and run the production readiness checklist before rollout.

Official sources

• Files API guide
• Files API reference
• Anthropic GA announcement

Source check: August 23, 2026. Recheck size and storage limits, expiration rules, audit coverage, data-retention eligibility, and account access before implementation.