Files ↗

Original Documentation

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 to share your experience with the Files API.

This feature is in beta and is not covered by Zero Data Retention (ZDR) 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_id instead 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:

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";

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:

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"
            }
          }
        ]
      }
    ]
  }'

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)


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
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	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:

# 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

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)



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();

For .docx files containing images, convert them to PDF format first, then use PDF support to take advantage of the built-in image parsing. This allows using citations from the PDF document.

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:

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()


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:

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")


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:

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")


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:

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"))



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);

You can only download files that were created by skills or the code execution tool. Files that you uploaded cannot be downloaded.

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.

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

{
  "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

Link last verified June 7, 2026. View original ↗

Source: Anthropic Platform Docs

Link last verified: 2026-02-26