26 KiB
Files API
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 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, in addition to this guide.
The Files API is currently in beta. Please reach out through our [feedback form](https://forms.gle/tisHyierGwgN4DUE9) to share your experience with the Files API. This feature is in beta and is **not** covered by [Zero Data Retention (ZDR)](/docs/en/build-with-claude/zero-data-retention) arrangements. Beta features are excluded from ZDR.Supported models
Referencing a file_id in a Messages request is supported in all models that support the given file type. For example, images are supported in all Claude 3+ models, PDFs in all Claude 3.5+ models, and various other file types for the code execution tool in Claude Haiku 4.5 plus all Claude 3.7+ models.
The Files API is currently not supported on Amazon Bedrock or Google Vertex AI.
How the Files API works
The Files API provides a simple create-once, use-many-times approach for working with files:
- Upload files to our secure storage and receive a unique
file_id - Download files that are created from skills or the code execution tool
- Reference files in Messages requests using the
file_idinstead of re-uploading content - Manage your files with list, retrieve, and delete operations
How to use the Files API
To use the Files API, you'll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`.Uploading a file
Upload a file to be referenced in future API calls:
```bash Shell 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" ```import anthropic
client = anthropic.Anthropic()
client.beta.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const anthropic = new Anthropic();
await anthropic.beta.files.upload({
file: await toFile(fs.createReadStream("/path/to/document.pdf"), undefined, { type: "application/pdf" })
}, {
betas: ["files-api-2025-04-14"]
});
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import java.nio.file.Path;
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var file = client.beta().files().upload(
Path.of("/path/to/document.pdf")
);
System.out.println(file.id());
package main
import (
"context"
"fmt"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
file, _ := os.Open("/path/to/document.pdf")
defer file.Close()
response, _ := client.Beta.Files.Upload(context.Background(),
anthropic.BetaFileUploadParams{
File: file,
})
fmt.Println(response.ID)
}
require "anthropic"
client = Anthropic::Client.new
file = client.beta.files.upload(
file: File.open("/path/to/document.pdf", "rb")
)
puts file.id
using Anthropic;
var client = new AnthropicClient();
var file = await client.Beta.Files.UploadAsync(
new FileUploadParams
{
File = File.OpenRead("/path/to/document.pdf")
});
Console.WriteLine(file.Id);
<?php
use Anthropic\Client;
$client = new Client(
apiKey: getenv("ANTHROPIC_API_KEY")
);
$file = $client->beta->files->upload([
'file' => fopen('/path/to/document.pdf', 'r')
]);
echo $file->id;
The response from uploading a file will include:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false
}
Using a file in messages
Once uploaded, reference the file using its file_id:
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
},
},
],
}
],
betas=["files-api-2025-04-14"],
)
print(response)
import { Anthropic } from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-6",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Please summarize this document for me."
},
{
type: "document",
source: {
type: "file",
file_id: "file_011CNha8iCJcU1wXNR6q4V8w"
}
}
]
}
],
betas: ["files-api-2025-04-14"]
});
console.log(response);
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(1024)
.addMessage(MessageParam.builder()
.role(Role.USER)
.content(ContentBlockParam.ofText("Please summarize this document for me."))
.content(ContentBlockParam.ofDocument(DocumentBlockParam.builder()
.source(DocumentBlockParam.Source.ofFile(
DocumentBlockParam.Source.File.builder()
.fileId("file_011CNha8iCJcU1wXNR6q4V8w")
.build()))
.build()))
.build())
.build();
Message message = client.beta().messages().create(params);
System.out.println(message);
package main
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
response, _ := client.Beta.Messages.New(context.Background(),
anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
Messages: []anthropic.BetaMessageParam{
{
Role: "user",
Content: []anthropic.BetaContentBlockParam{
anthropic.NewBetaTextBlock("Please summarize this document for me."),
{
Type: "document",
Source: &anthropic.BetaDocumentSourceParam{
Type: "file",
FileID: "file_011CNha8iCJcU1wXNR6q4V8w",
},
},
},
},
},
})
fmt.Println(response)
}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 1024,
betas: ["files-api-2025-04-14"],
messages: [
{
role: "user",
content: [
{ type: "text", text: "Please summarize this document for me." },
{
type: "document",
source: {
type: "file",
file_id: "file_011CNha8iCJcU1wXNR6q4V8w"
}
}
]
}
]
)
puts response
using Anthropic;
var client = new AnthropicClient();
var response = await client.Beta.Messages.CreateAsync(
new BetaMessageCreateParams
{
Model = "claude-opus-4-6",
MaxTokens = 1024,
Betas = new[] { "files-api-2025-04-14" },
Messages = new[]
{
new BetaMessageParam
{
Role = "user",
Content = new object[]
{
new { type = "text", text = "Please summarize this document for me." },
new
{
type = "document",
source = new
{
type = "file",
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
}
}
}
}
}
});
Console.WriteLine(response);
<?php
use Anthropic\Client;
$client = new Client(
apiKey: getenv("ANTHROPIC_API_KEY")
);
$response = $client->beta->messages->create([
'model' => 'claude-opus-4-6',
'max_tokens' => 1024,
'betas' => ['files-api-2025-04-14'],
'messages' => [
[
'role' => 'user',
'content' => [
['type' => 'text', 'text' => 'Please summarize this document for me.'],
[
'type' => 'document',
'source' => [
'type' => 'file',
'file_id' => 'file_011CNha8iCJcU1wXNR6q4V8w'
]
]
]
]
]
]);
print_r($response);
File types and content blocks
The Files API supports different file types that correspond to different content block types:
| File Type | MIME Type | Content Block Type | Use Case |
|---|---|---|---|
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 | Varies | container_upload |
Analyze data, create visualizations |
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:
curl https://api.anthropic.com/v1/messages
-H "content-type: application/json"
-H "x-api-key: $ANTHROPIC_API_KEY"
-H "anthropic-version: 2023-06-01"
-d @- <<EOF
{
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
}
]
}
]
}
EOF
```python Python
import pandas as pd
import anthropic
client = anthropic.Anthropic()
# Example: Reading a CSV file
df = pd.read_csv("data.csv")
csv_content = df.to_string()
# Send as plain text in the message
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
}
],
}
],
)
print(response.content[0].text)
import { Anthropic } from "@anthropic-ai/sdk";
import fs from "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-6",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: `Here's the document content:\n\n${textContent}\n\nPlease summarize this document.`
}
]
}
]
});
console.log(response.content[0].text);
}
analyzeDocument();
Document blocks
For PDFs and text files, use the document content block:
{
"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:
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}
Managing files
List files
Retrieve a list of your uploaded files:
```bash Shell curl 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" ```import anthropic
client = anthropic.Anthropic()
files = client.beta.files.list()
import { Anthropic } from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const files = await anthropic.beta.files.list({
betas: ["files-api-2025-04-14"]
});
Get file metadata
Retrieve information about a specific file:
```bash Shell curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: files-api-2025-04-14" ```import anthropic
client = anthropic.Anthropic()
file = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
import { Anthropic } from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const file = await anthropic.beta.files.retrieveMetadata(
"file_011CNha8iCJcU1wXNR6q4V8w",
{ betas: ["files-api-2025-04-14"] }
);
Delete a file
Remove a file from your workspace:
```bash Shell curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: files-api-2025-04-14" ```import anthropic
client = anthropic.Anthropic()
result = client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")
import { Anthropic } from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const result = await anthropic.beta.files.delete(
"file_011CNha8iCJcU1wXNR6q4V8w",
{ betas: ["files-api-2025-04-14"] }
);
Downloading a file
Download files that have been created by skills or the code execution tool:
```bash Shell curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: files-api-2025-04-14" \ --output downloaded_file.txt ```import anthropic
client = anthropic.Anthropic()
file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
# Save to file
with open("downloaded_file.txt", "w") as f:
f.write(file_content.decode("utf-8"))
import { Anthropic } from "@anthropic-ai/sdk";
import fs from "fs/promises";
const anthropic = new Anthropic();
const fileContent = await anthropic.beta.files.download(
"file_011CNha8iCJcU1wXNR6q4V8w",
{ betas: ["files-api-2025-04-14"] }
);
// Save to file
await fs.writeFile("downloaded_file.txt", fileContent);
File storage and limits
Storage limits
- Maximum file size: 500 MB per file
- Total storage: 100 GB per organization
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
- Deleted files cannot be recovered
- Files are inaccessible via the API shortly after deletion, but they may persist in active
MessagesAPI calls and associated tool uses - Files that users delete will be deleted in accordance with our data retention policy.
Error handling
Common errors when using the Files API include:
- File not found (404): The specified
file_iddoesn'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/messagesrequest) - Invalid filename (400): Filename 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 100 GB storage limit
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
}
}
Usage and billing
File API operations are free:
- Uploading files
- Downloading files
- Listing files
- Getting file metadata
- Deleting files
File content used in Messages requests are priced as input tokens. You can only download files created by skills or the code execution tool.
Rate limits
During the beta period:
- File-related API calls are limited to approximately 100 requests per minute
- Contact us if you need higher limits for your use case
Upload
post /v1/files
Upload File
Header Parameters
-
"anthropic-beta": optional array of AnthropicBetaOptional header to specify the beta version(s) you want to use.
-
UnionMember0 = string -
UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more-
"message-batches-2024-09-24" -
"prompt-caching-2024-07-31" -
"computer-use-2024-10-22" -
"computer-use-2025-01-24" -
"pdfs-2024-09-25" -
"token-counting-2024-11-01" -
"token-efficient-tools-2025-02-19" -
"output-128k-2025-02-19" -
"files-api-2025-04-14" -
"mcp-client-2025-04-04" -
"mcp-client-2025-11-20" -
"dev-full-thinking-2025-05-14" -
"interleaved-thinking-2025-05-14" -
"code-execution-2025-05-22" -
"extended-cache-ttl-2025-04-11" -
"context-1m-2025-08-07" -
"context-management-2025-06-27" -
"model-context-window-exceeded-2025-08-26" -
"skills-2025-10-02" -
"fast-mode-2026-02-01"
-
-
Returns
-
FileMetadata = object { id, created_at, filename, 4 more }-
id: stringUnique object identifier.
The format and length of IDs may change over time.
-
created_at: stringRFC 3339 datetime string representing when the file was created.
-
filename: stringOriginal filename of the uploaded file.
-
mime_type: stringMIME type of the file.
-
size_bytes: numberSize of the file in bytes.
-
type: "file"Object type.
For files, this is always
"file"."file"
-
downloadable: optional booleanWhether the file can be downloaded.
-
Example
curl https://api.anthropic.com/v1/files?beta=true \
-H 'Content-Type: multipart/form-data' \
-H 'anthropic-version: 2023-06-01' \
-H 'anthropic-beta: files-api-2025-04-14' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-F 'file=@/path/to/file'
List
get /v1/files
List Files
Query Parameters
-
after_id: optional stringID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
-
before_id: optional stringID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
-
limit: optional numberNumber of items to return per page.
Defaults to
20. Ranges from1to1000.
Header Parameters
-
"anthropic-beta": optional array of AnthropicBetaOptional header to specify the beta version(s) you want to use.
-
UnionMember0 = string -
UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more-
"message-batches-2024-09-24" -
"prompt-caching-2024-07-31" -
"computer-use-2024-10-22" -
"computer-use-2025-01-24" -
"pdfs-2024-09-25" -
"token-counting-2024-11-01" -
"token-efficient-tools-2025-02-19" -
"output-128k-2025-02-19" -
"files-api-2025-04-14" -
"mcp-client-2025-04-04" -
"mcp-client-2025-11-20" -
"dev-full-thinking-2025-05-14" -
"interleaved-thinking-2025-05-14" -
"code-execution-2025-05-22" -
"extended-cache-ttl-2025-04-11" -
"context-1m-2025-08-07" -
"context-management-2025-06-27" -
"model-context-window-exceeded-2025-08-26" -
"skills-2025-10-02" -
"fast-mode-2026-02-01"
-
-
Returns
-
data: array of FileMetadataList of file metadata objects.
-
id: stringUnique object identifier.
The format and length of IDs may change over time.
-
created_at: stringRFC 3339 datetime string representing when the file was created.
-
filename: stringOriginal filename of the uploaded file.
-
mime_type: stringMIME type of the file.
-
size_bytes: numberSize of the file in bytes.
-
type: "file"Object type.
For files, this is always
"file"."file"
-
downloadable: optional booleanWhether the file can be downloaded.
-
-
first_id: optional stringID of the first file in this page of results.
-
has_more: optional booleanWhether there are more results available.
-
last_id: optional stringID of the last file in this page of results.
Example
curl https://api.anthropic.com/v1/files?beta=true \
-H 'anthropic-version: 2023-06-01' \
-H 'anthropic-beta: files-api-2025-04-14' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
Download
get /v1/files/{file_id}/content
Download File
Path Parameters
-
file_id: stringID of the File.
Header Parameters
-
"anthropic-beta": optional array of AnthropicBetaOptional header to specify the beta version(s) you want to use.
-
UnionMember0 = string -
UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more-
"message-batches-2024-09-24" -
"prompt-caching-2024-07-31" -
"computer-use-2024-10-22" -
"computer-use-2025-01-24" -
"pdfs-2024-09-25" -
"token-counting-2024-11-01" -
"token-efficient-tools-2025-02-19" -
"output-128k-2025-02-19" -
"files-api-2025-04-14" -
"mcp-client-2025-04-04" -
"mcp-client-2025-11-20" -
"dev-full-thinking-2025-05-14" -
"interleaved-thinking-2025-05-14" -
"code-execution-2025-05-22" -
"extended-cache-ttl-2025-04-11" -
"context-1m-2025-08-07" -
"context-management-2025-06-27" -
"model-context-window-exceeded-2025-08-26" -
"skills-2025-10-02" -
"fast-mode-2026-02-01"
-
-
Example
curl https://api.anthropic.com/v1/files/$FILE_ID/content?beta=true \
-H 'anthropic-version: 2023-06-01' \
-H 'anthropic-beta: files-api-2025-04-14' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
Download
get /v1/files/{file_id}/content
Download File
Path Parameters
-
file_id: stringID of the File.
Header Parameters
-
"anthropic-beta": optional array of AnthropicBetaOptional header to specify the beta version(s) you want to use.
-
UnionMember0 = string -
UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more-
"message-batches-2024-09-24" -
"prompt-caching-2024-07-31" -
"computer-use-2024-10-22" -
"computer-use-2025-01-24" -
"pdfs-2024-09-25" -
"token-counting-2024-11-01" -
"token-efficient-tools-2025-02-19" -
"output-128k-2025-02-19" -
"files-api-2025-04-14" -
"mcp-client-2025-04-04" -
"mcp-client-2025-11-20" -
"dev-full-thinking-2025-05-14" -
"interleaved-thinking-2025-05-14" -
"code-execution-2025-05-22" -
"extended-cache-ttl-2025-04-11" -
"context-1m-2025-08-07" -
"context-management-2025-06-27" -
"model-context-window-exceeded-2025-08-26" -
"skills-2025-10-02" -
"fast-mode-2026-02-01"
-
-
Example
curl https://api.anthropic.com/v1/files/$FILE_ID/content?beta=true \
-H 'anthropic-version: 2023-06-01' \
-H 'anthropic-beta: files-api-2025-04-14' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"