data-files-api-reference-typescript

name	Data: Files API reference — TypeScript
description	TypeScript Files API reference including file upload, listing, deletion, and usage in messages
ccVersion	2.1.78
allowed-tools	Read Write Edit Bash
license	BSD-3-Clause license
metadata	{"skill-author":"Lord1Egypt"}

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

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

const response = await client.beta.messages.create({
  model: "{{OPUS_ID}}",
  max_tokens: 16000,
  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

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

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

Download a File

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