files changedbuild-with-claude/files
Nearest release: v2.1.307, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+33added
Lines−37removed
From line
29
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits24to this page, all time
The whole hunk
from line 29, old and new numbered
/
from line 29
2929* **Manage your files** with list, retrieve, and delete operations
3030
3131<Warning id="workspace-scoped-access">
32 **Uploaded files are accessible to your entire workspace, not scoped to an end user, conversation, or session.** Any API key with access to a workspace can access any files uploaded to that workspace. Every service account, and every user whose organization role allows API access, can use the Default Workspace in addition to any workspace you add them to, so keep files that must stay separate in their own [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping) and access them only with keys scoped to that workspace. Never accept `file_id` values from end users or other untrusted sources: a user-supplied file ID would let one user of your application read content that another user uploaded. Treat file IDs as server-side references, and keep the mapping between your users and their files in your application.
32 **Uploaded files are accessible to your entire workspace, not scoped to an end user, conversation, or session.** Any API key with access to a workspace can access any files uploaded to that workspace. Every service account, and every user whose organization role allows API access, can use the Default Workspace in addition to any workspace you add them to, so keep files that must stay separate in their own workspace and access them only with [keys scoped to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping). Never accept `file_id` values from end users or other untrusted sources: a user-supplied file ID would let one user of your application read content that another user uploaded. Treat file IDs as server-side references, and keep the mapping between your users and their files in your application.
3333
34 If you are building a multi-tenant application on the Files API, create a separate [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) for each tenant. The workspace is the isolation boundary for files, so a workspace per tenant gives each tenant's data hard isolation from every other tenant. Each organization can have up to 100 workspaces; contact your account team if you need more.
34 If you are building a multitenant application on the Files API, create a separate [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) for each tenant. The workspace is the isolation boundary for files, so a workspace for each tenant gives that tenant's data hard isolation from every other tenant. Each organization can have up to 100 workspaces; contact your account team if you need more.
3535</Warning>
3636
3737## How to use the Files API
from line 38
3838
3939### Uploading a file
4040
41Upload a file to be referenced in future API calls:
41Upload a file to reference in future API calls:
4242
4343<CodeGroup>
4444 ```bash cURL
from line 375
375375
376376The Files API supports different file types that correspond to different content block types:
377377
378| File type | MIME type | Content block type | Use case |
379| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------ | ----------------------------------- |
380| PDF | `application/pdf` | `document` | Text analysis, document processing |
381| Plain text | `text/plain` | `document` | Text analysis, processing |
382| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` | Image analysis, visual tasks |
383| [Datasets, others](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Varies | `container_upload` | Analyze data, create visualizations |
378| File type | MIME type | Content block type | Use case |
379| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------ | ---------------------------------- |
380| PDF | `application/pdf` | `document` | Text analysis, document processing |
381| Plain text | `text/plain` | `document` | Text analysis, processing |
382| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` | Image analysis, visual tasks |
383| [Datasets, others](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Varies | `container_upload` | Data analysis, visualization |
384384
385385#### Document blocks
386386
from line 752
752752 ```
753753
754754 ```bash CLI
755 ant files retrieve-metadata \
756 --file-id "$FILE_ID"
755 ant files retrieve-metadata --file-id "$FILE_ID"
757756 ```
758757
759758 ```python Python
from line 798
799798
800799#### Delete a file
801800
802Remove a file from your workspace:
801Delete a file from your workspace:
803802
804803<CodeGroup>
805804 ```bash cURL
from line 808
809808 ```
810809
811810 ```bash CLI
812 ant files delete \
813 --file-id "$FILE_ID"
811 ant files delete --file-id "$FILE_ID"
814812 ```
815813
816814 ```python Python
from line 852
854852 curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
855853 -H "x-api-key: $ANTHROPIC_API_KEY" \
856854 -H "anthropic-version: 2023-06-01" \
857 --output downloaded_file.txt
855 -o downloaded_file.txt
858856 ```
859857
860858 ```bash CLI
861 ant files download \
862 --file-id "$FILE_ID" \
863 --output downloaded_file.txt
859 ant files download --file-id "$FILE_ID" --output downloaded_file.txt
864860 ```
865861
866862 ```python Python
from line 930
934930
935931### Storage limits
936932
937* **Maximum file size:** 500 MB per file
938* **Total storage:** 1 TB per organization
933* **Maximum file size:** 500 MB for each file
934* **Total storage:** 1 TB for each organization
939935
940936### File lifecycle
941937
942* Files are scoped to the workspace they were uploaded in. Any request in the same workspace can reference them; never accept file IDs from untrusted sources (see the [workspace access warning](https://platform.claude.com/docs/en/build-with-claude/files#workspace-scoped-access))
943* Files cannot be modified or renamed after upload. To change a file's content, upload a new file and delete the old one
944* Files persist until you delete them with the `DELETE /v1/files/{file_id}` endpoint or they reach their `expires_at`
945* Deleted files cannot be recovered
946* Files are inaccessible through the API shortly after deletion, but they may persist in active Messages API calls and associated tool uses
947* Files that users delete will be deleted in accordance with Anthropic's [data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention)
938* Files are scoped to the workspace they were uploaded in. Any request in the same workspace can reference them; never accept file IDs from untrusted sources (see the [workspace access warning](https://platform.claude.com/docs/en/build-with-claude/files#workspace-scoped-access)).
939* Files cannot be modified or renamed after upload. To change a file's content, upload a new file and delete the old one.
940* Files persist until you delete them with the `DELETE /v1/files/{file_id}` endpoint or they reach their `expires_at`.
941* Deleted files cannot be recovered.
942* Files are inaccessible through the API shortly after deletion, but they may persist in active Messages API calls and associated tool uses.
943* Files that users delete will be deleted in accordance with Anthropic's [data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
948944
949945### File expiration
950946
from line 948
952948
953949When a file reaches its `expires_at`:
954950
955* Downloading its content (`GET /v1/files/{file_id}/content`) returns a 404 error
956* A Messages request that references the file fails before inference
957* Its metadata (`GET /v1/files/{file_id}`) remains readable for up to 30 days, with `expires_at` in the past
958* It continues to appear in list responses during that window; compare `expires_at` to the current time to filter expired files
951* Downloading its content (`GET /v1/files/{file_id}/content`) returns a 404 error.
952* A Messages request that references the file fails before inference.
953* Its metadata (`GET /v1/files/{file_id}`) remains readable for up to 30 days, with `expires_at` in the past.
954* It continues to appear in list responses during that window; compare `expires_at` to the current time to filter expired files.
959955
960956Deleting an expired file with `DELETE /v1/files/{file_id}` removes its metadata immediately instead of waiting for the 30-day window to elapse.
961957
962958<Note>
963 Expiration is a lifecycle feature, not a guaranteed-deletion control. After `expires_at`, file content is no longer retrievable through the API and is released from your storage quota; the underlying content may be retained for a limited period thereafter for safety review before permanent deletion, and file metadata remains visible for up to 30 days after expiration. To remove a file before its scheduled expiration, use `DELETE /v1/files/{file_id}`.
959 Expiration is a lifecycle feature, not a guaranteed-deletion control. After `expires_at`, file content is no longer retrievable through the API and is released from your storage quota; the underlying content may be retained for a limited period thereafter for safety review before permanent deletion, and file metadata remains visible for up to 30 days after expiration. To delete a file before its scheduled expiration, use `DELETE /v1/files/{file_id}`.
964960</Note>
965961
966962### Audit logging
from line 976
980976
981977To migrate:
982978
9831. **Remove the beta header.** Drop `anthropic-beta: files-api-2025-04-14` from your requests. In the SDKs, call `client.files` instead of `client.beta.files`; keeping `client.beta.files` works only on the [SDK releases that no longer send the header](https://platform.claude.com/docs/en/build-with-claude/files#sdk-beta-namespace). Earlier releases send it from `client.beta.files` even with no `betas` argument.
9791. **Remove the beta header.** Drop `anthropic-beta: files-api-2025-04-14` from your requests. With the SDK, call `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`) instead of `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`); keeping `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) works only on the [SDK releases that no longer send the header](https://platform.claude.com/docs/en/build-with-claude/files#sdk-beta-namespace). Earlier releases send it from `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) even when you pass no beta names.
9849802. **Update pagination.** Replace `after_id`/`before_id` loops with the `page`/`next_page` cursor, or use the SDK auto-pagination helpers shown in [Managing files](https://platform.claude.com/docs/en/build-with-claude/files#managing-files).
9859813. **Read `expires_at`.** The field appears only without the header; `null` means the file has no expiration (see [File expiration](https://platform.claude.com/docs/en/build-with-claude/files#file-expiration)).
986982
987983### SDK beta namespace
988984
989Starting with Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, and C# SDK 12.44.0, `client.beta.files` no longer sends `files-api-2025-04-14` and returns the same shapes as `client.files`, with `Beta`-prefixed type names. It accepts a `betas` argument for Files features that are still in beta, such as `scope_id` filtering under a [Managed Agents](https://platform.claude.com/docs/en/managed-agents/files) beta header. Earlier SDK releases are typed to the beta shapes; if you depend on those types, stay on an earlier release until you migrate.
985Starting with Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0, and C# SDK 12.44.0, `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) no longer sends `files-api-2025-04-14` and returns the same shapes as `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`), with `Beta`-prefixed type names (in PHP, classes in the `Anthropic\Beta` namespace). It takes beta names through `betas` (csharp, go: `Betas`; java: `.addBeta()`) for Files features that are in beta, such as `scope_id` filtering under a [Managed Agents](https://platform.claude.com/docs/en/managed-agents/files) beta header. Earlier SDK releases are typed to the beta shapes; if you depend on those types, stay on an earlier release until you migrate.
990986
991987Requests that carry `anthropic-beta: managed-agents-2026-04-01` without `files-api-2025-04-14` receive the shapes on this page with one compatibility affordance on `GET /v1/files`: `before_id` and `after_id` are still accepted (not combinable with `page` or `ids[]`), and the list response includes `has_more`, `first_id`, and `last_id` alongside `next_page`. Later Managed Agents beta versions receive the plain shape.
992988
from line 994
998994* **Invalid file type (400):** The file type doesn't match the content block type (for example, using an image file in a document block)
999995* **Not downloadable (400):** Files you upload have `"downloadable": false` and cannot be downloaded. Only files created by skills or the code execution tool can be downloaded
1000996* **Exceeds context window size (400):** The file is larger than the context window size (for example, using a 500 MB plain text file in a `/v1/messages` request)
1001* **Invalid filename (400):** The file name doesn't meet the length requirements (1-255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or Unicode characters 0-31)
997* **Invalid file name (400):** The file name doesn't meet the length requirements (1–255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or Unicode characters 0–31)
1002998* **File too large (413):** File exceeds the 500 MB limit
1003* **Storage limit exceeded (400):** Your organization has reached the 1 TB storage limit
999* **Storage limit exceeded (400):** Your organization has reached the 1 TB storage limit
10041000
10051001```json Output
10061002{
from line 1033
10371033 </Card>
10381034
10391035 <Card title="Code execution tool" icon="terminal" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool">
1040 Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
1036 Run Python and Bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
10411037 </Card>
10421038
10431039 <Card title="Vision" icon="image" href="https://platform.claude.com/docs/en/build-with-claude/vision">
No line in this hunk matches that.