TopolearnReusing an uploaded file keeps requests small and fast when the same document is used again and again.
Sending a PDF as Base64 in every request is wasteful: the same megabytes travel over the network each time. The Files API lets you upload a file once and get back an id like file_011C.... Afterwards you point at it with a source of {"type": "file", "file_id": ...}.
In late 2026 the Files API is generally available, so no beta flag is needed: use client.files.upload(...), client.files.list() and client.files.delete(file_id). Older examples use client.beta.files with a beta header; they still work but are the legacy form.
What it accepts:
- PDFs and plain text, used in
documentblocks. - JPEG, PNG, GIF and WebP images, used in
imageblocks. - Other files (like CSV datasets) for the code execution tool.
Uploading, listing and deleting are free; you pay only for the tokens when a file is used inside a message. Files stay until you delete them, or until an optional expiry you set at upload time.
One security detail matters: uploaded files are visible to the whole workspace (the group of API keys and resources in your organisation), not to a single end user. Never accept a file_id typed in by a user, or one customer could read another's file. Keep your own mapping of which user owns which file. You also cannot download files you uploaded; only files created by tools can be downloaded.
Example
import anthropic
client = anthropic.Anthropic()
with open("handbook.pdf", "rb") as f:
uploaded = client.files.upload(file=("handbook.pdf", f, "application/pdf"))
print(uploaded.id) # file_011C...
for question in ["How many vacation days?", "What is the dress code?"]:
msg = client.messages.create(
model="claude-opus-5-5",
max_tokens=300,
messages=[{"role": "user", "content": [
{"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
{"type": "text", "text": question},
]}],
)
print(msg.content[0].text)
client.files.delete(uploaded.id) # clean upRemember
- Upload once, reference by file_id many times
- Use
client.files(GA);client.beta.filesis the legacy form - Files are shared across the workspace; never trust user-supplied ids
Watch out for
- Letting end users pass arbitrary file_ids, which can leak other users' documents.