Anthropic Files API: Upload, Reuse, and Manage Files

The Anthropic Files API lets you upload a file once and refer to it by file_id in later Messages API requests. Start with Anthropic’s Files API guide for the workflow and its stable upload reference for request details. Anthropic currently labels the Files API stable. The API reference displays version 2026-10-21; use the version and headers documented for the endpoint you call, rather than treating a version label as a requirement by itself.

Files API endpoints

Operation	Method and route
Upload a file	POST /v1/files
List files	GET /v1/files
Get file metadata	GET /v1/files/{file_id}
Download file content	GET /v1/files/{file_id}/content
Delete a file	DELETE /v1/files/{file_id}

These are the routes in Anthropic’s Files API reference. The /api/beta/ reference is a separate beta-specific variant; use the stable reference for the stable workflow described here.

Upload a file and use it in a Messages request

This curl example uploads a plain-text file and then passes the returned ID in a document block. It uses Anthropic’s documented bearer authentication, API-version header, multipart upload, and file-reference shape. The example model, claude-sonnet-5-5, is listed in Anthropic’s current Files API compatibility information; file references work on models that support the relevant file type.

Set ANTHROPIC_API_KEY, install jq, and save the content you want Claude to read as notes.txt.

# Upload the file. curl -F creates the multipart boundary.
UPLOAD=$(curl -fsS https://api.anthropic.com/v1/files \
  -H "Authorization: Bearer ${ANTHROPIC_API_KEY}" \
  -H 'anthropic-version: 2026-10-21' \
  -F 'file=@./notes.txt;type=text/plain')

FILE_ID=$(printf '%s' "$UPLOAD" | jq -r '.id')
printf 'Uploaded file ID: %s\n' "$FILE_ID"

# Refer to that file in a Messages API request.
jq -n --arg file_id "$FILE_ID" '{
  model: "claude-sonnet-5-5",
  max_tokens: 256,
  messages: [{
    role: "user",
    content: [
      {type: "text", text: "Summarize this note in one sentence."},
      {type: "document", source: {type: "file", file_id: $file_id}}
    ]
  }]
}' | curl -fsS https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer ${ANTHROPIC_API_KEY}" \
  -H 'anthropic-version: 2026-10-21' \
  -H 'content-type: application/json' \
  --data-binary @-

A successful upload response includes an id; the Messages request uses it as source.file_id. Check the Messages response’s content for Claude’s answer. Plain-text files such as .txt, .csv, and .md can be used in document blocks with MIME type text/plain. The PDF support guide describes additional file-type and platform conditions; check it before adapting this example to another format or deployment.

List, inspect, download, and delete files

Use the file_id returned by upload to manage that file:

• List: GET /v1/files. The list endpoint defaults to 20 items per page and supports limit values from 1 to 1,000. If the response’s next_page is non-null, pass that cursor as the next request’s page parameter.
• Inspect metadata: GET /v1/files/{file_id}. Metadata includes the file ID, filename, MIME type, size, and a downloadable indicator; it may also include expires_at.
• Download: GET /v1/files/{file_id}/content. Check downloadable first; the guide describes downloads for files created by skills or the code execution tool, so do not assume every uploaded input can be downloaded.
• Delete: DELETE /v1/files/{file_id}. Anthropic says deleted files cannot be recovered and become inaccessible through the API shortly after deletion, though they may persist in active Messages API calls and associated tool use. The beta-specific delete reference shows a confirmation object with type file_deleted and the deleted file’s ID.

The upload reference supports optional expires_in_seconds values from 3,600 seconds (one hour) through 7,776,000 seconds (90 days). Set an expiration deliberately if needed; expiration is not a substitute for an application’s own data-handling policy.

Production checks

A workspace is the Files API access boundary—not an individual user, conversation, or session. Anthropic says any API key with access to a workspace can access files in that workspace. Keep file IDs and user-to-file authorization mappings server-side; do not treat a user-supplied file_id as proof of permission. For multitenant applications requiring tenant isolation, Anthropic recommends a separate workspace for each tenant and keys scoped to the appropriate workspace.

Before release, verify that the deployment and model support your intended file type and reference method, and test the complete upload, Messages, pagination, and cleanup flow. For PDF sources specifically, the platform guidance notes that Google-managed Claude on Google Cloud and Amazon Bedrock have a base64-only limitation; check the current platform documentation rather than assuming the Files API workflow is identical everywhere.

Anthropic’s API reference and guide are the sources for current request and lifecycle details. Do not rely on the 30 MB limit reported in an October 2025 third-party security article as a current limit; confirm applicable limits in the current upload reference and your account documentation.

Sources

Files API — Claude Platform Docs

Upload File — Claude API Reference

List Files — Claude API Reference

Download File — Claude API Reference

Delete File — Claude API Reference

API overview — Claude Platform Docs

Versions — Claude Platform Docs

PDF support — Claude Platform Docs

Messages — Claude API Reference

Files — Claude API Reference (beta-specific variant)

Files API — Anthropic Claude API skills

Claude Pirate: Abusing Anthropic’s File API For Data Exfiltration