files`)

Status: DOCUMENTED · LIVE_VERIFIED (upload txt/pdf/png, list, ids[] filter, legacy-header list, retrieve, content 400, use in Messages, delete, 404 after delete — 2026-09-18). GA since 2026-08-19: anthropic-beta: files-api-2025-04-14 is optional (LEGACY shape when sent). Not ZDR-eligible. Not on Bedrock/Vertex; beta on Claude Platform on AWS and Foundry (Hosted-on-Anthropic only). Sources: Files API guide · API reference (upload, list, metadata, download, delete) · Release notes Last verified: 2026-09-18 · Machine-readable: generated/fragments/endpoints/anthropic-files.json

# Endpoints

Method / path	Purpose	Request	Response	Live
`POST /v1/files`	Upload	`multipart/form-data`: `file` (binary; part `Content-Type` optional — an `application/octet-stream` .txt part was stored as `text/plain`), `expires_in_seconds` (3600–7,776,000)	`FileMetadata`	200 ×4
`GET /v1/files`	List (newest first)	query `limit` (20, 1–1000), `page` (cursor `page_…`), `ids[]` (≤ 100, single page, unknown ids omitted, exclusive with page/limit)	`{"data": [FileMetadata], "next_page": null}`	200
`GET /v1/files/{file_id}`	Metadata	—	`FileMetadata` (readable ≤ 30 days after expiry)	200; 404 after delete
`GET /v1/files/{file_id}/content`	Download	—	bytes — only files created by skills / code execution (`downloadable: true`); uploads → `400 File … is not downloadable. Only files generated by a tool (for example, the code execution tool) can be downloaded.`; expired → 404. Generated media carry C2PA credentials	400 (as documented)
`DELETE /v1/files/{file_id}`	Delete	—	`{"id": "file_…", "type": "file_deleted"}`	200

Optional header anthropic-workspace-id. Auth: x-api-key + anthropic-version: 2023-06-01. All operations are free; ~500 requests/min. SDKs: client.files.upload / list / retrieve_metadata / download / delete (client.beta.files no longer sends the beta header from Python 1.2.0 / TS 0.122.0).

# File object

json

{"type": "file", "id": "file_01EfVkMNzn7Yw7nQk38Rz6H2", "filename": "atlas.pdf", "mime_type": "application/pdf",
 "size_bytes": 607, "created_at": "2026-09-19T01:50:34.679190Z", "downloadable": false,
 "expires_at": "2026-09-19T02:50:34.679190Z"}

expires_at is null without expires_in_seconds; absent under the legacy header. Legacy list shape: {data, has_more, first_id, last_id} with before_id/after_id cursors (400 without the header). Filenames 1–255 chars, no < > : " | ? * \ / or control chars.

# Limits and lifecycle

Item	Value
Max file size	500 MB (413 above)
Org storage	1 TB (400 when exceeded)
Scope	workspace — any key in the workspace can read any file; never accept `file_id` from end users; one workspace per tenant (≤ 100 workspaces/org)
Mutability	immutable; upload a new file and delete the old one
Expiration	set once at upload (1 h – 90 d); after `expires_at` content → 404, Messages referencing it fail before inference, metadata visible 30 days; `DELETE` removes immediately. `expires_in_seconds: 60` → `400 expires_in_seconds: must be between 3600 and 7776000`
Deletion	irreversible; may persist briefly in in-flight requests
Audit	Compliance API activity feed records upload/download/delete (not list/metadata)

# Using files in Messages

MIME	Block	Example
`application/pdf`, `text/plain`	`document`	`{"type": "document", "source": {"type": "file", "file_id": "…"}, "citations": {"enabled": true}}`
`image/jpeg	png	gif
anything (datasets)	`container_upload`	`{"type": "container_upload", "file_id": "…"}` (code execution tool)

Mismatch → 400 PDF files cannot be used in image blocks. Use a document block instead. Content is billed as normal input tokens (live: 1-page PDF 1,599 tokens; 101-byte text with citations 613 tokens incl. citation system prompt; 1×1 PNG 21 tokens). Citations from file documents include file_id (undocumented) and document_title: null. Code-execution outputs expose their file_id in bash_code_execution_tool_result blocks — download those with /content.

# Errors

HTTP	Meaning
400	wrong block type, not downloadable, filename invalid, storage limit, `expires_in_seconds` range, file larger than the context window
404	`File … not found.` (deleted / other workspace / expired content)
413	> 500 MB

Examples: examples/anthropic/files/ (sh/py/ts) · tests: tests/anthropic/test_files.py.