Files API — TypeScript

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

Beta: Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

Key Facts

Maximum file size: 500 MB
Total storage: 100 GB per organization
Files persist until deleted
File operations (upload, list, delete) are free; content used in messages is billed as input tokens
Not available on Amazon Bedrock or Google Vertex AI

Upload a File

```typescript import Anthropic, { toFile } from "@anthropic-ai/sdk"; import fs from "fs";

const client = new Anthropic();

const uploaded = await client.beta.files.upload({ file: await toFile(fs.createReadStream("report.pdf"), undefined, { type: "application/pdf", }), betas: ["files-api-2025-04-14"], });

console.log(`File ID: ${uploaded.id}`); console.log(`Size: ${uploaded.size_bytes} bytes`); ```

Use a File in Messages

PDF / Text Document

```typescript const response = await client.beta.messages.create({ model: "claude-opus-4-6", max_tokens: 1024, messages: [ { role: "user", content: [ { type: "text", text: "Summarize the key findings in this report." }, { type: "document", source: { type: "file", file_id: uploaded.id }, title: "Q4 Report", citations: { enabled: true }, }, ], }, ], betas: ["files-api-2025-04-14"], });

console.log(response.content[0].text); ```

Manage Files

List Files

```typescript const files = await client.beta.files.list({ betas: ["files-api-2025-04-14"], }); for (const f of files.data) { console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`); } ```

Delete a File

```typescript await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", { betas: ["files-api-2025-04-14"], }); ```

Download a File

```typescript const response = await client.beta.files.download( "file_011CNha8iCJcU1wXNR6q4V8w", { betas: ["files-api-2025-04-14"] }, ); const content = Buffer.from(await response.arrayBuffer()); await fs.promises.writeFile("output.txt", content); ```

2.4 KiB Raw Blame History