files changedbuild-with-claude/files
Nearest release: v2.1.312, published under an hour before 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+15added
Lines−11removed
From line
23
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
The whole hunk
from line 23, old and new numbered
/
from line 23
2323
2424The Files API provides a create-once, use-many-times approach for working with files:
2525
26* **Upload files** to Anthropic's secure storage and receive a unique `file_id`
26* **Upload files** to Anthropic’s secure storage and receive a unique `file_id`
2727* **Download files** that are created by skills or the code execution tool
2828* **Reference files** in [Messages](https://platform.claude.com/docs/en/api/messages/create) requests using the `file_id` instead of re-uploading content
2929* **Manage your files** with list, retrieve, and delete operations
from line 31
3131<Warning id="workspace-scoped-access">
3232 **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 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.
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 156
156156}
157157```
158158
159`downloadable` is `false` for files you upload. Only files created by [skills](https://platform.claude.com/docs/en/build-with-claude/skills-guide) or the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) can be downloaded. See [Downloading a file](https://platform.claude.com/docs/en/build-with-claude/files#downloading-a-file).
159[`downloadable`](https://platform.claude.com/docs/en/api/files#file_metadata.downloadable) is `false` for files you upload. Only files created by [skills](https://platform.claude.com/docs/en/build-with-claude/skills-guide) or the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) can be downloaded. See [Downloading a file](https://platform.claude.com/docs/en/build-with-claude/files#downloading-a-file).
160160
161The API reference describes every field of the file object.
162
163(See `file_metadata` on `files` in [the API reference](https://platform.claude.com/docs/en/api/files#file_metadata).)
164
161165### Using a file in messages
162166
163167Once uploaded, reference the file by passing the `id` from the upload response as `file_id`:
from line 430
426430
427431### Working with other file formats
428432
429For file types that the `document` block doesn't support (for example, .docx and .xlsx), convert the files to plain text and include the content directly in your message. Files that are already plain text, such as .csv and .md files, can either be read in this way or uploaded through the Files API with an explicit `text/plain` content type. To analyze datasets instead of reading them as text, upload them for the code execution tool using a `container_upload` block (see [Upload and analyze your own files](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).
433For file types that the `document` block doesn’t support (for example, .docx and .xlsx), convert the files to plain text and include the content directly in your message. Files that are already plain text, such as .csv and .md files, can either be read in this way or uploaded through the Files API with an explicit `text/plain` content type. To analyze datasets instead of reading them as text, upload them for the code execution tool using a `container_upload` block (see [Upload and analyze your own files](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).
430434
431435The following examples read a text file and send its contents as plain text:
432436
from line 672
668672
669673#### List files
670674
671Retrieve a list of your uploaded files. The endpoint is paginated: each request returns up to `limit` files (20 by default, and at most 1,000), and the response's `next_page` cursor fetches the next page when passed back as the `page` parameter. Files are ordered newest first. See the [List Files API reference](https://platform.claude.com/docs/en/api/files/list). The SDK returns the first page and provides [auto-pagination](https://platform.claude.com/docs/en/api/overview#pagination) helpers.
675Retrieve a list of your uploaded files. The endpoint is paginated: each request returns up to [`limit`](https://platform.claude.com/docs/en/api/files/list#list.limit) files (20 by default, and at most 1,000), and the response’s [`next_page`](https://platform.claude.com/docs/en/api/files/list#list.response.next_page) cursor fetches the next page when passed back as the [`page`](https://platform.claude.com/docs/en/api/files/list#list.page) parameter. Files are ordered newest first. See the [List Files API reference](https://platform.claude.com/docs/en/api/files/list). The SDK returns the first page and provides [auto-pagination](https://platform.claude.com/docs/en/api/overview#pagination) helpers.
672676
673677<CodeGroup>
674678 ```bash cURL
from line 939
935939### File lifecycle
936940
937941* 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)).
938* Files cannot be modified or renamed after upload. To change a file's content, upload a new file and delete the old one.
942* Files cannot be modified or renamed after upload. To change a file’s content, upload a new file and delete the old one.
939943* Files persist until you delete them with the `DELETE /v1/files/{file_id}` endpoint or they reach their `expires_at`.
940944* Deleted files cannot be recovered.
941945* Files are inaccessible through the API shortly after deletion, but they may persist in active Messages API calls and associated tool uses.
942* 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).
946* 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).
943947
944948### File expiration
945949
946To have a file expire automatically, include an `expires_in_seconds` form field when you upload it. The value is an integer number of seconds between 3,600 (1 hour) and 7,776,000 (90 days). The resulting `expires_at` timestamp (RFC 3339) appears on every file response and is `null` for files uploaded without an expiration. Expiration is set once at upload and cannot be changed.
950To have a file expire automatically, include an [`expires_in_seconds`](https://platform.claude.com/docs/en/api/files/upload#upload.expires_in_seconds) form field when you upload it. The value is an integer number of seconds between 3,600 (1 hour) and 7,776,000 (90 days). The resulting [`expires_at`](https://platform.claude.com/docs/en/api/files#file_metadata.expires_at) timestamp (RFC 3339) appears on every file response and is `null` for files uploaded without an expiration. Expiration is set once at upload and cannot be changed.
947951
948952When a file reaches its `expires_at`:
949953
from line 993
989993
990994Common errors when using the Files API include:
991995
992* **File not found (404):** The specified `file_id` doesn't exist or you don't have access to it.
993* **Invalid file type (400):** The file type doesn't match the content block type (for example, using an image file in a document block).
996* **File not found (404):** The specified `file_id` doesn’t exist or you don’t have access to it.
997* **Invalid file type (400):** The file type doesn’t match the content block type (for example, using an image file in a document block).
994998* **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.
995999* **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).
996* **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).
1000* **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).
9971001* **File too large (413):** The file exceeds the 500 MB limit.
9981002* **Storage limit exceeded (400):** Your organization has reached the 1 TB storage limit.
9991003
No line in this hunk matches that.