Files API (Anthropic Compatible)¶

Upload and manage files via an Anthropic-compatible interface. Files are stored in Amazon S3 and can be referenced directly in Messages requests as document or image sources.

Simple Upload
Upload any file with a single multipart/form-data request. Files are immediately available for use in inference.
Bidirectional Pagination
Traverse your file list in both directions using after_id and before_id cursors, just like the Anthropic SDK's Page<T> interface.
Messages Integration
Reference uploaded files directly in Messages requests as document or image source blocks using "type": "file".
Content Download
Download raw file bytes at any time via the /content endpoint.

Available Endpoints¶

Endpoint	Method	Description
`/v1/files`	`POST`	Upload a file
`/v1/files`	`GET`	List files with pagination
`/v1/files/{file_id}`	`GET`	Retrieve file metadata
`/v1/files/{file_id}`	`DELETE`	Delete a file
`/v1/files/{file_id}/content`	`GET`	Download raw file bytes

Feature Compatibility¶

Feature	Status	Notes
Upload
`file` (multipart)		Required binary form field
Listing
`after_id` cursor		Forward cursor: returns files newer than the given ID
`before_id` cursor		Backward cursor: returns files older than the given ID
`limit`		1 – 1 000; default 20
File size cap		No artificial limit; S3 object limit (~5 TB)
Messages integration		`"source": {"type": "file", "file_id": "..."}` in document/image
`downloadable` field		Always `true`; spec default is `false` for user-uploaded files

Legend:

Supported — Fully compatible with Anthropic API
Partial — Implemented with minor deviations from spec
Extra Feature — Enhanced capability beyond Anthropic API

Quick Start¶

Upload a File¶

curl -X POST "$BASE/v1/files" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@document.pdf;type=application/pdf"

Response:

{
  "id": "file_0190c51c7de7455d9b8c2efe27dfbf67",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 102400,
  "created_at": "2025-04-15T12:00:00Z",
  "downloadable": true
}

Retrieve Metadata¶

curl "$BASE/v1/files/file_0190c51c7de7455d9b8c2efe27dfbf67" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14"

List Files¶

# Default (oldest first, up to 20 files)
curl "$BASE/v1/files" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14"

# Forward pagination: files after a given ID
curl "$BASE/v1/files?after_id=file_0190c51c7de7455d9b8c2efe27dfbf67&limit=20" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14"

# Backward pagination: files before a given ID
curl "$BASE/v1/files?before_id=file_0190c51c7de7455d9b8c2efe27dfbf67" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14"

Download Content¶

curl "$BASE/v1/files/file_0190c51c7de7455d9b8c2efe27dfbf67/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -o downloaded.pdf

Delete a File¶

curl -X DELETE "$BASE/v1/files/file_0190c51c7de7455d9b8c2efe27dfbf67" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14"

Response:

{
  "id": "file_0190c51c7de7455d9b8c2efe27dfbf67",
  "type": "file_deleted"
}

Messages Integration¶

Reference an uploaded file inside a POST /v1/messages request as a document or image source:

Document (PDF or other supported format):

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_0190c51c7de7455d9b8c2efe27dfbf67"
            }
          },
          {
            "type": "text",
            "text": "Summarise this document."
          }
        ]
      }
    ]
  }'

Image:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "file_0190c51c7de7455d9b8c2efe27dfbf68"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

Using the Anthropic Python SDK¶

import io
from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8000", api_key="...")

# Upload
file = client.beta.files.upload(
    file=("document.pdf", open("document.pdf", "rb"), "application/pdf")
)
print(f"Uploaded: {file.id}")

# Reference in a message
response = client.beta.messages.create(
    model="anthropic.claude-haiku-4-5-20251001-v1:0",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file.id},
                },
                {
                    "type": "text",
                    "text": "What is the key finding in this document?",
                },
            ],
        }
    ],
)
print(response.content[0].text)

# Cleanup
client.beta.files.delete(file.id)

Paginating with the SDK¶

The Anthropic SDK's Page object supports forward and backward traversal:

# List all files (auto-paginated)
page = client.beta.files.list(limit=50)
for file in page.data:
    print(file.id, file.filename)

# Forward cursor
next_page = client.beta.files.list(after_id=page.last_id)

# Backward cursor
prev_page = client.beta.files.list(before_id=page.first_id)

Error Reference¶

HTTP	Cause
400	Invalid filename characters
404	File not found or already deleted
503	`AWS_S3_BUCKET` is not configured

Configuration¶

Files are stored in S3 under the prefix configured by AWS_S3_FILES_PREFIX (default: files/). All file IDs are shared across the OpenAI and Anthropic endpoints — a file uploaded via one API can be downloaded or deleted via the other.

Use files across multiple requests without re-uploading. See OpenAI Files API for the OpenAI-compatible equivalent, including expires_after support.