1150 lines
26 KiB
Markdown
1150 lines
26 KiB
Markdown
# 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](/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.
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
## Supported models
|
|
|
|
Referencing a `file_id` in a Messages request is supported in all models that support the given file type. For example, [images](/docs/en/build-with-claude/vision) are supported in all Claude 3+ models, [PDFs](/docs/en/build-with-claude/pdf-support) in all Claude 3.5+ models, and [various other file types](/docs/en/agents-and-tools/tool-use/code-execution-tool#supported-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](/docs/en/api/messages) 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`.
|
|
</Note>
|
|
|
|
### Uploading a file
|
|
|
|
Upload a file to be referenced in future API calls:
|
|
|
|
<CodeGroup>
|
|
```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"
|
|
```
|
|
|
|
```python Python
|
|
import anthropic
|
|
|
|
client = anthropic.Anthropic()
|
|
client.beta.files.upload(
|
|
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
|
|
)
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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"]
|
|
});
|
|
```
|
|
|
|
```java Java
|
|
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());
|
|
```
|
|
|
|
```go Go
|
|
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)
|
|
}
|
|
```
|
|
|
|
```ruby Ruby
|
|
require "anthropic"
|
|
|
|
client = Anthropic::Client.new
|
|
|
|
file = client.beta.files.upload(
|
|
file: File.open("/path/to/document.pdf", "rb")
|
|
)
|
|
|
|
puts file.id
|
|
```
|
|
|
|
```csharp C#
|
|
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 PHP
|
|
<?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;
|
|
```
|
|
</CodeGroup>
|
|
|
|
The response from uploading a file will include:
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
<CodeGroup>
|
|
```bash Shell
|
|
curl -X POST https://api.anthropic.com/v1/messages \
|
|
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
|
-H "anthropic-version: 2023-06-01" \
|
|
-H "anthropic-beta: files-api-2025-04-14" \
|
|
-H "content-type: application/json" \
|
|
-d '{
|
|
"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"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
```python Python
|
|
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)
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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);
|
|
```
|
|
|
|
```java Java
|
|
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);
|
|
```
|
|
|
|
```go Go
|
|
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)
|
|
}
|
|
```
|
|
|
|
```ruby Ruby
|
|
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
|
|
```
|
|
|
|
```csharp C#
|
|
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 PHP
|
|
<?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);
|
|
```
|
|
</CodeGroup>
|
|
|
|
### 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 |
|
|
| :--- | :--- | :--- | :--- |
|
|
| 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#supported-file-types) | 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:
|
|
|
|
<CodeGroup>
|
|
```bash Shell
|
|
# Example: Reading a text file and sending it as plain text
|
|
# Note: For files with special characters, consider base64 encoding
|
|
TEXT_CONTENT=$(cat document.txt | jq -Rs .)
|
|
|
|
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)
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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();
|
|
```
|
|
</CodeGroup>
|
|
|
|
<Note>
|
|
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:
|
|
|
|
<CodeGroup>
|
|
```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"
|
|
```
|
|
|
|
```python Python
|
|
import anthropic
|
|
|
|
client = anthropic.Anthropic()
|
|
files = client.beta.files.list()
|
|
```
|
|
|
|
```typescript TypeScript
|
|
import { Anthropic } from "@anthropic-ai/sdk";
|
|
|
|
const anthropic = new Anthropic();
|
|
const files = await anthropic.beta.files.list({
|
|
betas: ["files-api-2025-04-14"]
|
|
});
|
|
```
|
|
</CodeGroup>
|
|
|
|
#### Get file metadata
|
|
|
|
Retrieve information about a specific file:
|
|
|
|
<CodeGroup>
|
|
```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"
|
|
```
|
|
|
|
```python Python
|
|
import anthropic
|
|
|
|
client = anthropic.Anthropic()
|
|
file = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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"] }
|
|
);
|
|
```
|
|
</CodeGroup>
|
|
|
|
#### Delete a file
|
|
|
|
Remove a file from your workspace:
|
|
|
|
<CodeGroup>
|
|
```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"
|
|
```
|
|
|
|
```python Python
|
|
import anthropic
|
|
|
|
client = anthropic.Anthropic()
|
|
result = client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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"] }
|
|
);
|
|
```
|
|
</CodeGroup>
|
|
|
|
### Downloading a file
|
|
|
|
Download files that have been created by skills or the code execution tool:
|
|
|
|
<CodeGroup>
|
|
```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
|
|
```
|
|
|
|
```python Python
|
|
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"))
|
|
```
|
|
|
|
```typescript TypeScript
|
|
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);
|
|
```
|
|
</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.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## 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 `Messages` API calls and associated tool uses
|
|
- Files that users delete will be deleted in accordance with our [data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data).
|
|
|
|
---
|
|
|
|
## 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)
|
|
- **File too large (413):** File exceeds the 500 MB limit
|
|
- **Storage limit exceeded (403):** Your organization has reached the 100 GB storage limit
|
|
|
|
```json
|
|
{
|
|
"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](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool).
|
|
|
|
### Rate limits
|
|
|
|
During the beta period:
|
|
- 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
|
|
|
|
---
|
|
|
|
## Upload
|
|
|
|
**post** `/v1/files`
|
|
|
|
Upload File
|
|
|
|
### Header Parameters
|
|
|
|
- `"anthropic-beta": optional array of AnthropicBeta`
|
|
|
|
Optional 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: string`
|
|
|
|
Unique object identifier.
|
|
|
|
The format and length of IDs may change over time.
|
|
|
|
- `created_at: string`
|
|
|
|
RFC 3339 datetime string representing when the file was created.
|
|
|
|
- `filename: string`
|
|
|
|
Original filename of the uploaded file.
|
|
|
|
- `mime_type: string`
|
|
|
|
MIME type of the file.
|
|
|
|
- `size_bytes: number`
|
|
|
|
Size of the file in bytes.
|
|
|
|
- `type: "file"`
|
|
|
|
Object type.
|
|
|
|
For files, this is always `"file"`.
|
|
|
|
- `"file"`
|
|
|
|
- `downloadable: optional boolean`
|
|
|
|
Whether the file can be downloaded.
|
|
|
|
### Example
|
|
|
|
```http
|
|
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 string`
|
|
|
|
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
|
|
|
|
- `before_id: optional string`
|
|
|
|
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
|
|
|
|
- `limit: optional number`
|
|
|
|
Number of items to return per page.
|
|
|
|
Defaults to `20`. Ranges from `1` to `1000`.
|
|
|
|
### Header Parameters
|
|
|
|
- `"anthropic-beta": optional array of AnthropicBeta`
|
|
|
|
Optional 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 FileMetadata`
|
|
|
|
List of file metadata objects.
|
|
|
|
- `id: string`
|
|
|
|
Unique object identifier.
|
|
|
|
The format and length of IDs may change over time.
|
|
|
|
- `created_at: string`
|
|
|
|
RFC 3339 datetime string representing when the file was created.
|
|
|
|
- `filename: string`
|
|
|
|
Original filename of the uploaded file.
|
|
|
|
- `mime_type: string`
|
|
|
|
MIME type of the file.
|
|
|
|
- `size_bytes: number`
|
|
|
|
Size of the file in bytes.
|
|
|
|
- `type: "file"`
|
|
|
|
Object type.
|
|
|
|
For files, this is always `"file"`.
|
|
|
|
- `"file"`
|
|
|
|
- `downloadable: optional boolean`
|
|
|
|
Whether the file can be downloaded.
|
|
|
|
- `first_id: optional string`
|
|
|
|
ID of the first file in this page of results.
|
|
|
|
- `has_more: optional boolean`
|
|
|
|
Whether there are more results available.
|
|
|
|
- `last_id: optional string`
|
|
|
|
ID of the last file in this page of results.
|
|
|
|
### Example
|
|
|
|
```http
|
|
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: string`
|
|
|
|
ID of the File.
|
|
|
|
### Header Parameters
|
|
|
|
- `"anthropic-beta": optional array of AnthropicBeta`
|
|
|
|
Optional 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
|
|
|
|
```http
|
|
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: string`
|
|
|
|
ID of the File.
|
|
|
|
### Header Parameters
|
|
|
|
- `"anthropic-beta": optional array of AnthropicBeta`
|
|
|
|
Optional 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
|
|
|
|
```http
|
|
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"
|
|
```
|
|
|