# Anthropic — Files API (`/v1/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](https://platform.claude.com/docs/en/build-with-claude/files) · [API reference](https://platform.claude.com/docs/en/api/files) ([upload](https://platform.claude.com/docs/en/api/files/upload), [list](https://platform.claude.com/docs/en/api/files/list), [metadata](https://platform.claude.com/docs/en/api/files/retrieve_metadata), [download](https://platform.claude.com/docs/en/api/files/download), [delete](https://platform.claude.com/docs/en/api/files/delete)) · [Release notes](https://platform.claude.com/docs/en/release-notes/api)
**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|webp` | `image` | `{"type": "image", "source": {"type": "file", "file_id": "…"}}` |
| 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`.