files changedbuild-with-claude/files
Nearest release: v2.1.238, published under 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+66added
Lines−95removed
From line
9
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 9, old and new numbered
/
from line 9
99- Platforms: Claude API, Claude Platform on AWS (beta), Microsoft Foundry (beta) [1]; not available on Amazon Bedrock, Google Cloud
10101. On [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), the Files API requires a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
1111
12The Files API lets you upload and manage files to use with the Claude API without re-uploading content with each request. This is particularly useful when using the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) to provide inputs (for example, datasets and documents) and then download outputs (for example, charts). You can [explore the API reference directly](https://platform.claude.com/docs/en/api/beta/files/upload), in addition to this guide.
12The Files API lets you upload and manage files to use with the Claude API without re-uploading content with each request. This is particularly useful when using the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) to provide inputs (for example, datasets and documents) and then download outputs (for example, charts). You can [explore the API reference directly](https://platform.claude.com/docs/en/api/files/upload), in addition to this guide.
1313
1414## File type support
1515
from line 33
3333## How to use the Files API
3434
3535<Note>
36 Requests to the Files API endpoints (`/v1/files`) don't need a beta header, and neither do Messages or Message Batches requests that reference an uploaded file. Two things to know about the `anthropic-beta: files-api-2025-04-14` header the examples on this page still send:
37
38 * **Referencing a file from the Messages API.** Requests that use an uploaded file as a `document` or `image` source, or in a `container_upload` block for the code execution tool, work with or without the header. The SDK examples on this page still pass it through their `betas` parameter, which continues to work.
39 * **Sending the header on Files API requests.** The SDK `beta.files` methods and the CLI `ant beta:files` commands add the header automatically, and the cURL examples on this page include it. Those requests keep working and return the earlier response format: the list endpoint paginates with `before_id` and `after_id`, returns `has_more`, `first_id`, and `last_id` instead of `next_page`, and rejects the `page` and `ids[]` parameters as unknown fields. File objects returned under the header omit `expires_at` instead of returning `null` when no expiration is set. To use `page` and `ids[]` as described under [List files](https://platform.claude.com/docs/en/build-with-claude/files#list-files), send the request without the beta header.
36 Requests to the Files API endpoints (`/v1/files`) don't need a beta header. Neither do Messages or Message Batches requests that reference an uploaded file as a `document` or `image` source, or in a `container_upload` block for the code execution tool. Requests that still send the `anthropic-beta: files-api-2025-04-14` header keep working. On Files API requests, that header also selects the earlier response format: the list endpoint paginates with `before_id` and `after_id`, returns `has_more`, `first_id`, and `last_id` instead of `next_page`, and rejects the `page` and `ids[]` parameters as unknown fields. File objects returned under the header omit `expires_at` instead of returning `null` when no expiration is set. To use `page` and `ids[]` as described under [List files](https://platform.claude.com/docs/en/build-with-claude/files#list-files), send the request without the header. The PHP tabs on this page still call the SDK's `beta` namespace, which sends the header, so their list output uses the earlier format.
4037</Note>
4138
4239### Uploading a file
from line 45
4845 FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
4946 -H "x-api-key: $ANTHROPIC_API_KEY" \
5047 -H "anthropic-version: 2023-06-01" \
51 -H "anthropic-beta: files-api-2025-04-14" \
5248 -F "file=@/path/to/document.pdf" | jq -r '.id')
5349 echo "$FILE_ID"
5450 ```
5551
5652 ```bash CLI
57 FILE_ID=$(ant beta:files upload \
53 FILE_ID=$(ant files upload \
5854 --file /path/to/document.pdf \
5955 --transform id \
6056 --raw-output)
from line 58
6258 ```
6359
6460 ```python Python
65 uploaded = client.beta.files.upload(
61 uploaded = client.files.upload(
6662 file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
6763 )
6864 file_id = uploaded.id
from line 66
7066 ```
7167
7268 ```typescript TypeScript
73 const uploaded = await client.beta.files.upload({
69 const uploaded = await client.files.upload({
7470 file: await toFile(
7571 fs.createReadStream("/path/to/document.pdf"),
7672 undefined,
from line 77
8177 ```
8278
8379 ```csharp C#
84 var uploaded = await client.Beta.Files.Upload(
80 var uploaded = await client.Files.Upload(
8581 new FileUploadParams
8682 {
8783 File = new BinaryContent
from line 99
10399 }
104100 defer f.Close()
105101
106 response, err := client.Beta.Files.Upload(context.Background(),
107 anthropic.BetaFileUploadParams{
102 response, err := client.Files.Upload(context.Background(),
103 anthropic.FileUploadParams{
108104 File: anthropic.File(f, "document.pdf", "application/pdf"),
109105 })
110106 if err != nil {
from line 112
116112 ```
117113
118114 ```java Java
119 FileMetadata file = client.beta().files().upload(
115 FileMetadata file = client.files().upload(
120116 FileUploadParams.builder()
121117 .file(MultipartField.<InputStream>builder()
122118 .value(Files.newInputStream(Path.of("/path/to/document.pdf")))
from line 136
140136 ```
141137
142138 ```ruby Ruby
143 file = client.beta.files.upload(
139 file = client.files.upload(
144140 file: Anthropic::FilePart.new(
145141 Pathname("/path/to/document.pdf"),
146142 content_type: "application/pdf"
from line 174
178174 curl -X POST https://api.anthropic.com/v1/messages \
179175 -H "x-api-key: $ANTHROPIC_API_KEY" \
180176 -H "anthropic-version: 2023-06-01" \
181 -H "anthropic-beta: files-api-2025-04-14" \
182177 -H "content-type: application/json" \
183178 -d @- <<EOF
184179 {
from line 202
207202 ```
208203
209204 ```bash CLI
210 ant beta:messages create --beta files-api-2025-04-14 <<YAML
205 ant messages create <<YAML
211206 model: claude-opus-5
212207 max_tokens: 1024
213208 messages:
from line 218
223218 ```
224219
225220 ```python Python
226 response = client.beta.messages.create(
221 response = client.messages.create(
227222 model="claude-opus-5",
228223 max_tokens=1024,
229224 messages=[
from line 236
241236 ],
242237 }
243238 ],
244 betas=["files-api-2025-04-14"],
245239 )
246240 print(response)
247241 ```
248242
249243 ```typescript TypeScript
250 const response = await client.beta.messages.create({
244 const response = await client.messages.create({
251245 model: "claude-opus-5",
252246 max_tokens: 1024,
253247 messages: [
from line 262
268262 ],
269263 },
270264 ],
271 betas: ["files-api-2025-04-14"],
272265 });
273266
274267 console.log(response);
from line 268
275268 ```
276269
277270 ```csharp C#
278 var response = await client.Beta.Messages.Create(
271 var response = await client.Messages.Create(
279272 new MessageCreateParams
280273 {
281 Model = Messages::Model.ClaudeOpus5,
274 Model = Model.ClaudeOpus5,
282275 MaxTokens = 1024,
283 Betas = [AnthropicBeta.FilesApi2025_04_14],
284276 Messages =
285277 [
286 new BetaMessageParam
278 new MessageParam
287279 {
288280 Role = Role.User,
289 Content = new List<BetaContentBlockParam>
281 Content = new List<ContentBlockParam>
290282 {
291 new BetaTextBlockParam { Text = "Please summarize this document for me." },
292 new BetaRequestDocumentBlock
283 new TextBlockParam { Text = "Please summarize this document for me." },
284 new DocumentBlockParam
293285 {
294 Source = new BetaFileDocumentSource { FileID = fileId }
286 Source = new FileDocumentSource { FileID = fileId }
295287 }
296288 }
297289 }
from line 294
302294 ```
303295
304296 ```go Go
305 msg, err := client.Beta.Messages.New(context.Background(),
306 anthropic.BetaMessageNewParams{
297 msg, err := client.Messages.New(context.Background(),
298 anthropic.MessageNewParams{
307299 Model: anthropic.ModelClaudeOpus5,
308300 MaxTokens: 1024,
309 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
310 Messages: []anthropic.BetaMessageParam{
311 anthropic.NewBetaUserMessage(
312 anthropic.NewBetaTextBlock("Please summarize this document for me."),
313 anthropic.NewBetaDocumentBlock(anthropic.BetaFileDocumentSourceParam{
301 Messages: []anthropic.MessageParam{
302 anthropic.NewUserMessage(
303 anthropic.NewTextBlock("Please summarize this document for me."),
304 anthropic.NewDocumentBlock(anthropic.FileDocumentSourceParam{
314305 FileID: fileID,
315306 }),
316307 ),
from line 317
326317 ```java Java
327318 MessageCreateParams params = MessageCreateParams.builder()
328319 .model(Model.CLAUDE_OPUS_5)
329 .addBeta("files-api-2025-04-14")
330320 .maxTokens(1024)
331 .addUserMessageOfBetaContentBlockParams(List.of(
332 BetaContentBlockParam.ofText(BetaTextBlockParam.builder()
321 .addUserMessageOfBlockParams(List.of(
322 ContentBlockParam.ofText(TextBlockParam.builder()
333323 .text("Please summarize this document for me.")
334324 .build()),
335 BetaContentBlockParam.ofDocument(BetaRequestDocumentBlock.builder()
336 .source(BetaFileDocumentSource.builder()
337 .fileId(fileId)
338 .build())
325 ContentBlockParam.ofDocument(DocumentBlockParam.builder()
326 .fileSource(fileId)
339327 .build())
340328 ))
341329 .build();
342330
343 BetaMessage message = client.beta().messages().create(params);
331 Message message = client.messages().create(params);
344332 System.out.println(message);
345333 ```
346334
from line 358
370358 ```
371359
372360 ```ruby Ruby
373 response = client.beta.messages.create(
361 response = client.messages.create(
374362 model: "claude-opus-5",
375363 max_tokens: 1024,
376 betas: ["files-api-2025-04-14"],
377364 messages: [
378365 {
379366 role: "user",
from line 686
699686
700687#### List files
701688
702Retrieve 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/beta/files/list). The SDKs return the first page and provide auto-pagination helpers. The CLI example bounds the total with `--max-items`:
689Retrieve 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 SDKs return the first page and provide auto-pagination helpers. The CLI example bounds the total with `--max-items`:
703690
704691<CodeGroup>
705692 ```bash cURL
706693 curl https://api.anthropic.com/v1/files \
707694 -H "x-api-key: $ANTHROPIC_API_KEY" \
708 -H "anthropic-version: 2023-06-01" \
709 -H "anthropic-beta: files-api-2025-04-14"
695 -H "anthropic-version: 2023-06-01"
710696 ```
711697
712698 ```bash CLI
713 ant beta:files list \
699 ant files list \
714700 --max-items 10
715701 ```
716702
717703 ```python Python
718704 client = anthropic.Anthropic()
719 files = client.beta.files.list()
705 files = client.files.list()
720706 print(files)
721707 ```
722708
723709 ```typescript TypeScript
724710 const client = new Anthropic();
725 const files = await client.beta.files.list();
711 const files = await client.files.list();
726712 console.log(files);
727713 ```
728714
from line 715
729715 ```csharp C#
730716 AnthropicClient client = new();
731717
732 var files = await client.Beta.Files.List();
718 var files = await client.Files.List();
733719 Console.WriteLine(files);
734720 ```
735721
from line 722
736722 ```go Go
737723 client := anthropic.NewClient()
738724
739 files, err := client.Beta.Files.List(context.TODO(), anthropic.BetaFileListParams{})
725 files, err := client.Files.List(context.TODO(), anthropic.FileListParams{})
740726 if err != nil {
741727 log.Fatal(err)
742728 }
from line 730
744730 ```
745731
746732 ```java Java
747 import com.anthropic.models.beta.files.FileListPage;
733 import com.anthropic.models.files.FileListPage;
748734 // ...
749735 void main() {
750736 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
751737
752 FileListPage files = client.beta().files().list();
738 FileListPage files = client.files().list();
753739 System.out.println(files);
754740 }
755741 ```
from line 750
764750 ```ruby Ruby
765751 client = Anthropic::Client.new
766752
767 files = client.beta.files.list
753 files = client.files.list
768754 puts files
769755 ```
770756</CodeGroup>
from line 757
771757
772758To check a known set of files in one request instead of paging, pass up to 100 file IDs as `ids[]` query parameters. An `ids[]` request always returns a single page (`next_page` is `null`), and any ID that does not resolve to a file in your workspace is silently omitted from `data`; compare the returned IDs against the requested IDs to detect misses. `ids[]` cannot be combined with `page` or `limit`.
773759
774The `page` parameter, the `next_page` cursor, and the `ids[]` filter apply to requests sent without the `anthropic-beta: files-api-2025-04-14` header. The preceding examples send it (the SDKs and CLI add it for `beta.files` calls), so they receive the earlier list format described in the note under [How to use the Files API](https://platform.claude.com/docs/en/build-with-claude/files#how-to-use-the-files-api).
760The `page` parameter, the `next_page` cursor, and the `ids[]` filter apply to requests sent without the `anthropic-beta: files-api-2025-04-14` header. Requests that send the header receive the earlier list format described in the note under [How to use the Files API](https://platform.claude.com/docs/en/build-with-claude/files#how-to-use-the-files-api).
775761
776762#### Get file metadata
777763
from line 767
781767 ```bash cURL
782768 curl "https://api.anthropic.com/v1/files/$FILE_ID" \
783769 -H "x-api-key: $ANTHROPIC_API_KEY" \
784 -H "anthropic-version: 2023-06-01" \
785 -H "anthropic-beta: files-api-2025-04-14"
770 -H "anthropic-version: 2023-06-01"
786771 ```
787772
788773 ```bash CLI
789 ant beta:files retrieve-metadata \
774 ant files retrieve-metadata \
790775 --file-id "$FILE_ID"
791776 ```
792777
793778 ```python Python
794 file = client.beta.files.retrieve_metadata(file_id)
779 file = client.files.retrieve_metadata(file_id)
795780 print(file)
796781 ```
797782
798783 ```typescript TypeScript
799 const file = await client.beta.files.retrieveMetadata(uploaded.id);
784 const file = await client.files.retrieveMetadata(uploaded.id);
800785 console.log(file);
801786 ```
802787
803788 ```csharp C#
804 var file = await client.Beta.Files.RetrieveMetadata(fileId);
789 var file = await client.Files.RetrieveMetadata(fileId);
805790 Console.WriteLine(file);
806791 ```
807792
808793 ```go Go
809 metadata, err := client.Beta.Files.GetMetadata(
810 context.TODO(),
811 fileID,
812 anthropic.BetaFileGetMetadataParams{},
813 )
794 metadata, err := client.Files.GetMetadata(context.TODO(), fileID)
814795 if err != nil {
815796 log.Fatal(err)
816797 }
from line 800
819800 ```
820801
821802 ```java Java
822 FileMetadata metadata = client.beta().files().retrieveMetadata(fileId);
803 FileMetadata metadata = client.files().retrieveMetadata(fileId);
823804
824805 System.out.println(metadata);
825806 ```
from line 811
830811 ```
831812
832813 ```ruby Ruby
833 file = client.beta.files.retrieve_metadata(file_id)
814 file = client.files.retrieve_metadata(file_id)
834815 puts file
835816 ```
836817</CodeGroup>
from line 824
843824 ```bash cURL
844825 curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
845826 -H "x-api-key: $ANTHROPIC_API_KEY" \
846 -H "anthropic-version: 2023-06-01" \
847 -H "anthropic-beta: files-api-2025-04-14"
827 -H "anthropic-version: 2023-06-01"
848828 ```
849829
850830 ```bash CLI
851 ant beta:files delete \
831 ant files delete \
852832 --file-id "$FILE_ID"
853833 ```
854834
855835 ```python Python
856 client.beta.files.delete(file_id)
836 client.files.delete(file_id)
857837 ```
858838
859839 ```typescript TypeScript
860 await client.beta.files.delete(uploaded.id);
840 await client.files.delete(uploaded.id);
861841 ```
862842
863843 ```csharp C#
864 await client.Beta.Files.Delete(fileId);
844 await client.Files.Delete(fileId);
865845 ```
866846
867847 ```go Go
868 _, err = client.Beta.Files.Delete(
869 context.TODO(),
870 fileID,
871 anthropic.BetaFileDeleteParams{},
872 )
848 _, err = client.Files.Delete(context.TODO(), fileID)
873849 if err != nil {
874850 log.Fatal(err)
875851 }
from line 852
876852 ```
877853
878854 ```java Java
879 client.beta().files().delete(fileId);
855 client.files().delete(fileId);
880856 ```
881857
882858 ```php PHP
from line 860
884860 ```
885861
886862 ```ruby Ruby
887 client.beta.files.delete(file_id)
863 client.files.delete(file_id)
888864 ```
889865</CodeGroup>
890866
from line 873
897873 curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
898874 -H "x-api-key: $ANTHROPIC_API_KEY" \
899875 -H "anthropic-version: 2023-06-01" \
900 -H "anthropic-beta: files-api-2025-04-14" \
901876 --output downloaded_file.txt
902877 ```
903878
904879 ```bash CLI
905 ant beta:files download \
880 ant files download \
906881 --file-id "$FILE_ID" \
907882 --output downloaded_file.txt
908883 ```
909884
910885 ```python Python
911 file_content = client.beta.files.download(file_id)
886 file_content = client.files.download(file_id)
912887
913888 file_content.write_to_file("downloaded_file.txt")
914889 ```
915890
916891 ```typescript TypeScript
917 const content = await client.beta.files.download(uploaded.id);
892 const content = await client.files.download(uploaded.id);
918893
919894 const bytes = Buffer.from(await content.arrayBuffer());
920895 await fsp.writeFile("downloaded_file.txt", bytes);
from line 896
921896 ```
922897
923898 ```csharp C#
924 using var fileContent = await client.Beta.Files.Download(fileId);
899 using var fileContent = await client.Files.Download(fileId);
925900 await using var source = await fileContent.ReadAsStream();
926901 await using var destination = File.Create("downloaded_file.txt");
927902 await source.CopyToAsync(destination);
from line 904
929904
930905 ```go Go
931906 func downloadFile(client anthropic.Client, fileID string) error {
932 resp, err := client.Beta.Files.Download(
933 context.TODO(),
934 fileID,
935 anthropic.BetaFileDownloadParams{},
936 )
907 resp, err := client.Files.Download(context.TODO(), fileID)
937908 if err != nil {
938909 return err
939910 }
from line 923
952923 ```
953924
954925 ```java Java
955 try (HttpResponse response = client.beta().files().download(fileId)) {
926 try (HttpResponse response = client.files().download(fileId)) {
956927 try (InputStream body = response.body()) {
957928 Files.copy(body, Path.of("downloaded_file.txt"),
958929 StandardCopyOption.REPLACE_EXISTING);
from line 938
967938 ```
968939
969940 ```ruby Ruby
970 file_content = client.beta.files.download(file_id)
941 file_content = client.files.download(file_id)
971942
972943 File.binwrite("downloaded_file.txt", file_content.read)
973944 ```
No line in this hunk matches that.