← Back to daily report

build-with-claude/files.md

Changed on 2026-07-06 15:48:50 EST

Unified Diff

--- a/build-with-claude/files.md
+++ b/build-with-claude/files.md
@@ -1,8 +1,10 @@
 # Files API
 
+Upload files once, reference them by file_id in Messages requests, and download outputs created by skills or the code execution tool.
+
 ---
 
-The 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](/docs/en/agents-and-tools/tool-use/code-execution-tool) to provide inputs (e.g. datasets and documents) and then download outputs (e.g. charts). You can also use the Files API to prevent having to continually re-upload frequently used documents and images across multiple API calls. You can [explore the API reference directly](/docs/en/api/files-create), in addition to this guide.
+The 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](/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](/docs/en/api/files-create), in addition to this guide.
 
 <Note>
   The Files API is in beta. Reach out through the [feedback form](https://forms.gle/tisHyierGwgN4DUE9) to share your experience with the Files API.
@@ -20,17 +22,17 @@
 
 ## How the Files API works
 
-The Files API provides a simple create-once, use-many-times approach for working with files:
+The Files API provides a create-once, use-many-times approach for working with files:
 
 * **Upload files** to Anthropic's secure storage and receive a unique `file_id`
-* **Download files** that are created from skills or the code execution tool
+* **Download files** that are created by skills or the code execution tool
 * **Reference files** in [Messages](/docs/en/api/messages/create) requests using the `file_id` instead of re-uploading content
 * **Manage your files** with list, retrieve, and delete operations
 
 ## How to use the Files API
 
 <Note>
-  To use the Files API, you'll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`.
+  To use the Files API, you'll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`. The SDKs add this header automatically when you call methods on the `beta.files` namespace, so the SDK examples on this page don't pass it explicitly for file operations. Messages requests that reference a file do need it, which the SDK examples pass through their `betas` parameter.
 </Note>
 
 ### Uploading a file
@@ -39,23 +41,28 @@
 
 <CodeGroup>
   ```bash cURL
-  curl -X POST https://api.anthropic.com/v1/files \
+  FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "anthropic-beta: files-api-2025-04-14" \
-    -F "file=@/path/to/document.pdf"
+    -F "file=@/path/to/document.pdf" | jq -r '.id')
+  echo "$FILE_ID"
   ```
 
   ```bash CLI
   FILE_ID=$(ant beta:files upload \
     --file /path/to/document.pdf \
-    --transform id --raw-output)
+    --transform id \
+    --raw-output)
+  echo "$FILE_ID"
   ```
 
   ```python Python
   uploaded = client.beta.files.upload(
       file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
   )
+  file_id = uploaded.id
+  print(file_id)
   ```
 
   ```typescript TypeScript
@@ -66,6 +73,7 @@
       { type: "application/pdf" },
     ),
   });
+  console.log(uploaded.id);
   ```
 
   ```csharp C#
@@ -80,7 +88,8 @@
           }
       });
 
-  Console.WriteLine(uploaded.ID);
+  var fileId = uploaded.ID;
+  Console.WriteLine(fileId);
   ```
 
   ```go Go
@@ -98,7 +107,8 @@
   	log.Fatal(err)
   }
 
-  fmt.Println(response.ID)
+  fileID := response.ID
+  fmt.Println(fileID)
   ```
 
   ```java Java
@@ -112,7 +122,8 @@
           .build()
   );
 
-  System.out.println(file.id());
+  String fileId = file.id();
+  System.out.println(fileId);
   ```
 
   ```php PHP
@@ -120,7 +131,8 @@
       FileParam::fromResource(fopen('/path/to/document.pdf', 'rb'), contentType: 'application/pdf'),
   );
 
-  echo $file->id;
+  $fileId = $file->id;
+  echo $fileId;
   ```
 
   ```ruby Ruby
@@ -131,13 +143,14 @@
     )
   )
 
-  puts file.id
+  file_id = file.id
+  puts file_id
   ```
 </CodeGroup>
 
-The response from uploading a file will include:
-
-```json Output
+The response from uploading a file includes:
+
+```json Response
 {
   "id": "file_011CNha8iCJcU1wXNR6q4V8w",
   "type": "file",
@@ -149,9 +162,11 @@
 }
 ```
 
+`downloadable` is `false` for files you upload. Only files created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) can be downloaded. See [Downloading a file](#downloading-a-file).
+
 ### Using a file in messages
 
-Once uploaded, reference the file using its `file_id`:
+Once uploaded, reference the file by passing the `id` from the upload response as `file_id`:
 
 <CodeGroup>
   ```bash cURL
@@ -379,22 +394,67 @@
 
 The Files API supports different file types that correspond to different content block types:
 
-| File Type                                                                                                    | MIME Type                                            | Content Block Type | Use Case                            |
+| File type                                                                                                    | MIME type                                            | Content block type | Use case                            |
 | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ------------------ | ----------------------------------- |
 | PDF                                                                                                          | `application/pdf`                                    | `document`         | Text analysis, document processing  |
 | Plain text                                                                                                   | `text/plain`                                         | `document`         | Text analysis, processing           |
 | Images                                                                                                       | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`            | Image analysis, visual tasks        |
 | [Datasets, others](/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Varies                                               | `container_upload` | Analyze data, create visualizations |
 
+#### Document blocks
+
+For PDFs and text files, use the `document` content block:
+
+```json
+{
+  "type": "document",
+  "source": {
+    "type": "file",
+    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
+  },
+  "title": "Document Title", // Optional
+  "context": "Context about the document", // Optional
+  "citations": { "enabled": true } // Optional, enables citations
+}
+```
+
+#### Image blocks
+
+For images, use the `image` content block:
+
+```json
+{
+  "type": "image",
+  "source": {
+    "type": "file",
+    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
+  }
+}
+```
+
+#### Container upload blocks
+
+To send a file to the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), use the `container_upload` content block:
+
+```json
+{
+  "type": "container_upload",
+  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
+}
+```
+
 ### Working with other file formats
 
-For file types that are not supported as `document` blocks (.csv, .txt, .md, .docx, .xlsx), convert the files to plain text, and include the content directly in your message:
+For 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](/docs/en/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) using a `container_upload` block.
+
+The following examples read a text file and send its contents as plain text:
 
 <CodeGroup>
   ```bash cURL
-  # Example: Reading a text file and sending it as plain text
+  # Read the text file
   # Note: For files with special characters, consider base64 encoding
-  # ...
+  TEXT_CONTENT=$(cat document.txt)
+
   curl https://api.anthropic.com/v1/messages \
     -H "content-type: application/json" \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
@@ -423,7 +483,8 @@
   ant messages create \
     --model claude-opus-4-8 \
     --max-tokens 1024 \
-    --transform 'content.0.text' --raw-output <<'YAML'
+    --transform 'content.0.text' \
+    --raw-output <<'YAML'
   messages:
     - role: user
       content:
@@ -437,13 +498,12 @@
   ```
 
   ```python Python
-  import pandas as pd
-  # ...
-  # Example: Reading a CSV file
-  df = pd.read_csv("data.csv")
-  csv_content = df.to_string()
-
-  # Send as plain text in the message
+  client = anthropic.Anthropic()
+
+  # Read the text file
+  with open("document.txt") as f:
+      text_content = f.read()
+
   response = client.messages.create(
       model="claude-opus-4-8",
       max_tokens=1024,
@@ -453,7 +513,7 @@
               "content": [
                   {
                       "type": "text",
-                      "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
+                      "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                   }
               ],
           }
@@ -465,115 +525,85 @@
 
   ```typescript TypeScript
   import fs from "node:fs/promises";
-
-  const anthropic = new Anthropic();
-
-  async function analyzeDocument() {
-    // Example: Reading a text file
-    const textContent = await fs.readFile("document.txt", "utf-8");
-
-    // Send as plain text in the message
-    const response = await anthropic.messages.create({
-      model: "claude-opus-4-8",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: [
-            {
-              type: "text",
-              text: `Here's the document content:\n\n${textContent}\n\nPlease summarize this document.`
-            }
-          ]
-        }
-      ]
-    });
-
-    const block = response.content[0];
-    if (block.type === "text") {
-      console.log(block.text);
-    }
-  }
-
-  analyzeDocument();
+  // ...
+  const client = new Anthropic();
+
+  // Read the text file
+  const textContent = await fs.readFile("document.txt", "utf-8");
+
+  const response = await client.messages.create({
+    model: "claude-opus-4-8",
+    max_tokens: 1024,
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: `Here's the document content:\n\n${textContent}\n\nPlease summarize this document.`
+          }
+        ]
+      }
+    ]
+  });
+
+  const block = response.content[0];
+  if (block.type === "text") {
+    console.log(block.text);
+  }
   ```
 
   ```csharp C#
-  using System;
-  using System.IO;
-  using System.Threading.Tasks;
-  using Anthropic;
-  using Anthropic.Models.Messages;
-
-  class Program
+  AnthropicClient client = new();
+
+  // Read the text file
+  string textContent = await File.ReadAllTextAsync("document.txt");
+
+  var parameters = new MessageCreateParams
   {
-      static async Task Main(string[] args)
+      Model = Model.ClaudeOpus4_8,
+      MaxTokens = 1024,
+      Messages = [new()
       {
-          AnthropicClient client = new();
-
-          // Example: Reading a text file
-          string textContent = await File.ReadAllTextAsync("document.txt");
-
-          var parameters = new MessageCreateParams
-          {
-              Model = Model.ClaudeOpus4_8,
-              MaxTokens = 1024,
-              Messages = [new()
-              {
-                  Role = Role.User,
-                  Content = $"Here's the document content:\n\n{textContent}\n\nPlease summarize this document."
-              }]
-          };
-
-          var message = await client.Messages.Create(parameters);
-          Console.WriteLine(message);
-      }
-  }
+          Role = Role.User,
+          Content = $"Here's the document content:\n\n{textContent}\n\nPlease summarize this document."
+      }]
+  };
+
+  var message = await client.Messages.Create(parameters);
+  Console.WriteLine(message);
   ```
 
   ```go Go
-  package main
-
-  import (
-  	"context"
-  	"fmt"
-  	"log"
-  	"os"
-
-  	"github.com/anthropics/anthropic-sdk-go"
-  )
-  // ...
-  func main() {
-  	client := anthropic.NewClient()
-
-  	// Example: Reading a text file
-  	textContent, err := os.ReadFile("document.txt")
-  	if err != nil {
-  		log.Fatal(err)
-  	}
-
-  	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
-  		Model:     anthropic.ModelClaudeOpus4_8,
-  		MaxTokens: 1024,
-  		Messages: []anthropic.MessageParam{
-  			anthropic.NewUserMessage(anthropic.NewTextBlock(
-  				fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
-  			)),
-  		},
-  	})
-  	if err != nil {
-  		log.Fatal(err)
-  	}
-
-  	fmt.Println(response.Content[0].Text)
-  }
+  client := anthropic.NewClient()
+
+  // Read the text file
+  textContent, err := os.ReadFile("document.txt")
+  if err != nil {
+  	log.Fatal(err)
+  }
+
+  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
+  	Model:     anthropic.ModelClaudeOpus4_8,
+  	MaxTokens: 1024,
+  	Messages: []anthropic.MessageParam{
+  		anthropic.NewUserMessage(anthropic.NewTextBlock(
+  			fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
+  		)),
+  	},
+  })
+  if err != nil {
+  	log.Fatal(err)
+  }
+
+  fmt.Println(response.Content[0].Text)
   ```
 
   ```java Java
   AnthropicClient client = AnthropicOkHttpClient.fromEnv();
 
-  // Example: Reading a text file
-  String textContent = Files.readString(Paths.get("document.txt"));
+  // Read the text file
+  String textContent = Files.readString(Path.of("document.txt"));
 
   MessageCreateParams params = MessageCreateParams.builder()
       .model(Model.CLAUDE_OPUS_4_8)
@@ -590,7 +620,7 @@
   ```php PHP
   $client = new Client();
 
-  // Example: Reading a text file
+  // Read the text file
   $textContent = file_get_contents("document.txt");
 
   $message = $client->messages->create(
@@ -615,7 +645,7 @@
   ```ruby Ruby
   client = Anthropic::Client.new
 
-  # Example: Reading a text file
+  # Read the text file
   text_content = File.read("document.txt")
 
   message = client.messages.create(
@@ -642,42 +672,11 @@
   For .docx files containing images, convert them to PDF format first, then use [PDF support](/docs/en/build-with-claude/pdf-support) to take advantage of the built-in image parsing. This allows using citations from the PDF document.
 </Note>
 
-#### Document blocks
-
-For PDFs and text files, use the `document` content block:
-
-```json
-{
-  "type": "document",
-  "source": {
-    "type": "file",
-    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
-  },
-  "title": "Document Title", // Optional
-  "context": "Context about the document", // Optional
-  "citations": { "enabled": true } // Optional, enables citations
-}
-```
-
-#### Image blocks
-
-For images, use the `image` content block:
-
-```json
-{
-  "type": "image",
-  "source": {
-    "type": "file",
-    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
-  }
-}
-```
-
 ### Managing files
 
 #### List files
 
-Retrieve a list of your uploaded files:
+Retrieve a list of your uploaded files. The endpoint is paginated: each request returns up to `limit` files (20 by default), and the `before_id` and `after_id` parameters fetch the adjacent page. See the [List Files API reference](/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`:
 
 <CodeGroup>
   ```bash cURL
@@ -688,35 +687,27 @@
   ```
 
   ```bash CLI
-  ant beta:files list
+  ant beta:files list \
+    --max-items 10
   ```
 
   ```python Python
   client = anthropic.Anthropic()
   files = client.beta.files.list()
+  print(files)
   ```
 
   ```typescript TypeScript
-  const anthropic = new Anthropic();
-  const files = await anthropic.beta.files.list();
+  const client = new Anthropic();
+  const files = await client.beta.files.list();
+  console.log(files);
   ```
 
   ```csharp C#
-  using System;
-  using System.Threading.Tasks;
-  using Anthropic;
-  using Anthropic.Models.Beta.Files;
-
-  class Program
-  {
-      static async Task Main(string[] args)
-      {
-          AnthropicClient client = new();
-
-          var files = await client.Beta.Files.List();
-          Console.WriteLine(files);
-      }
-  }
+  AnthropicClient client = new();
+
+  var files = await client.Beta.Files.List();
+  Console.WriteLine(files);
   ```
 
   ```go Go
@@ -732,10 +723,12 @@
   ```java Java
   import com.anthropic.models.beta.files.FileListPage;
   // ...
-          AnthropicClient client = AnthropicOkHttpClient.fromEnv();
-
-          FileListPage files = client.beta().files().list();
-          System.out.println(files);
+  void main() {
+      AnthropicClient client = AnthropicOkHttpClient.fromEnv();
+
+      FileListPage files = client.beta().files().list();
+      System.out.println(files);
+  }
   ```
 
   ```php PHP
@@ -772,10 +765,12 @@
 
   ```python Python
   file = client.beta.files.retrieve_metadata(file_id)
+  print(file)
   ```
 
   ```typescript TypeScript
   const file = await client.beta.files.retrieveMetadata(uploaded.id);
+  console.log(file);
   ```
 
   ```csharp C#
@@ -831,7 +826,7 @@
   ```
 
   ```python Python
-  result = client.beta.files.delete(file_id)
+  client.beta.files.delete(file_id)
   ```
 
   ```typescript TypeScript
@@ -858,17 +853,17 @@
   ```
 
   ```php PHP
-  $result = $client->beta->files->delete($fileId);
+  $client->beta->files->delete($fileId);
   ```
 
   ```ruby Ruby
-  result = client.beta.files.delete(file_id)
+  client.beta.files.delete(file_id)
   ```
 </CodeGroup>
 
 ### Downloading a file
 
-Download files that have been created by skills or the code execution tool:
+Download files that were created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool). Files you upload cannot be downloaded. The `file_id` of a generated file appears in the [`code_execution_tool_result` content block](/docs/en/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) of the Messages response that created it:
 
 <CodeGroup>
   ```bash cURL
@@ -888,7 +883,6 @@
   ```python Python
   file_content = client.beta.files.download(file_id)
 
-  # Save to file
   file_content.write_to_file("downloaded_file.txt")
   ```
 
@@ -951,10 +945,8 @@
 </CodeGroup>
 
 <Note>
-  You can only download files that were created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool). Files that you uploaded cannot be downloaded.
+  A file is downloadable only when its metadata shows `"downloadable": true`, which is the case for files created by skills or the code execution tool. Downloading a file you uploaded returns a 400 error.
 </Note>
-
-***
 
 ## File storage and limits
 
@@ -965,44 +957,39 @@
 
 ### File lifecycle
 
-* Files are scoped to the workspace of the API key. Other API keys can use files created by any other API key associated with the same workspace
-* Files persist until you delete them
+* Files are scoped to the workspace of the API key that uploaded them. Any API key in the same workspace can reference them
+* Files cannot be modified or renamed after upload. To change a file's content, upload a new file and delete the old one
+* Files persist until you delete them with the `DELETE /v1/files/{file_id}` endpoint
 * Deleted files cannot be recovered
-* Files are inaccessible via the API shortly after deletion, but they may persist in active `Messages` API calls and associated tool uses
-* 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).
-
-***
-
-## Data retention
-
-Files uploaded via the Files API are retained until explicitly deleted using the `DELETE /v1/files/{file_id}` endpoint. Files are stored for reuse across multiple API requests.
-
-For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
+* Files are inaccessible through the API shortly after deletion, but they may persist in active Messages API calls and associated tool uses
+* 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](/docs/en/manage-claude/api-and-data-retention)
 
 ## Error handling
 
 Common errors when using the Files API include:
 
 * **File not found (404):** The specified `file_id` doesn't exist or you don't have access to it
-* **Invalid file type (400):** The file type doesn't match the content block type (e.g., using an image file in a document block)
-* **Exceeds context window size (400):** The file is larger than the context window size (e.g. using a 500 MB plaintext file in a `/v1/messages` request)
-* **Invalid filename (400):** Filename doesn't meet the length requirements (1-255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or unicode characters 0-31)
+* **Invalid file type (400):** The file type doesn't match the content block type (for example, using an image file in a document block)
+* **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
+* **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)
+* **Invalid filename (400):** The file name doesn't meet the length requirements (1-255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or Unicode characters 0-31)
 * **File too large (413):** File exceeds the 500 MB limit
-* **Storage limit exceeded (403):** Your organization has reached the 500 GB storage limit
+* **Storage limit exceeded (400):** Your organization has reached the 500 GB storage limit
 
 ```json Output
 {
   "type": "error",
   "error": {
-    "type": "invalid_request_error",
-    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
-  }
+    "type": "not_found_error",
+    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
+  },
+  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
 }
 ```
 
 ## Usage and billing
 
-File API operations are **free**:
+Files API operations are free:
 
 * Uploading files
 * Downloading files
@@ -1010,7 +997,7 @@
 * Getting file metadata
 * Deleting files
 
-File content used in `Messages` requests are priced as input tokens. You can only download files created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool).
+File content used in Messages requests is priced as input tokens.
 
 ### Rate limits
 
@@ -1018,3 +1005,19 @@
 
 * File-related API calls are limited to approximately 100 requests per minute
 * [Contact us](mailto:sales@anthropic.com) if you need higher limits for your use case
+
+## Next steps
+
+<CardGroup cols={3}>
+  <Card title="PDF support" icon="file" href="/docs/en/build-with-claude/pdf-support">
+    Process PDFs with Claude. Extract text, analyze charts, and understand visual content from your documents.
+  </Card>
+
+  <Card title="Code execution tool" icon="terminal" href="/docs/en/agents-and-tools/tool-use/code-execution-tool">
+    Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
+  </Card>
+
+  <Card title="Vision" icon="image" href="/docs/en/build-with-claude/vision">
+    Process and analyze visual input and generate text and code from images.
+  </Card>
+</CardGroup>