# Python Files API

Use the Files API when you need upload-once, reference-many behavior across multiple Claude API requests.

## Important constraints

- Files API is beta.
- Include the Files API beta header/version accepted by your SDK release.
- Uploaded files cannot be downloaded later; only files generated by skills or code execution are downloadable.
- Files API is not supported on Bedrock or Vertex AI.

## Upload a file

```python
from anthropic import Anthropic

client = Anthropic()

with open("document.pdf", "rb") as f:
    meta = client.beta.files.upload(
        file=("document.pdf", f, "application/pdf"),
    )

print(meta.id)
```

## Reference the file in a message

```python
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this PDF."},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": meta.id},
                },
            ],
        }
    ],
)
```

## Manage files

```python
files = client.beta.files.list()
info = client.beta.files.retrieve_metadata(meta.id)
client.beta.files.delete(meta.id)
```

## Practical guidance

- Prefer Files API when the same document, image, or dataset is reused.
- Validate MIME type and size before upload.
- Track `file_id` in your own storage.
- Delete files you no longer need; file persistence is explicit.

## Official references

- Files API guide: `https://platform.claude.com/docs/en/build-with-claude/files`
- Python Files API reference: `https://platform.claude.com/docs/en/api/python/beta/files`
