Files API shipping

Stop re-uploading the same 200-page contract.

Without the Files API, every API call that needs a big document re-sends the full bytes. With it, you upload once, get a file_id, and reference that ID. Combine with prompt caching and the document loads at a tiny fraction of the cost on each follow-up call.

Three calls.

1. POST /v1/files with the file. Get back a file_id.
2. Reference it in messages as {"type":"document","source":{"type":"file","file_id":"…"}}.
3. Combine with prompt caching — mark the document as cacheable so subsequent calls hit the cache.

file = client.files.upload(file=open("contract.pdf","rb"))
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role":"user",
        "content":[
            {"type":"document","source":{"type":"file","file_id":file.id},
             "cache_control":{"type":"ephemeral"}},
            {"type":"text","text":"Summarize the indemnity clauses."}
        ]
    }]
)

The accepted shapes.

• PDFs — Claude reads pages and figures.
• Images — JPG, PNG, GIF, WebP.
• Plain text & code — .txt, .md, source files.
• Structured data — CSV, JSON, XML.
• Archives — small zips of code, useful for "review this repo" shapes.

Don't make these mistakes.

• List your files. They don't auto-expire (in most plans). Build a janitor that deletes anything older than X days.
• Tag with metadata — origin, owner, retention. Future-you will thank you.
• Don't upload secrets. Strip API keys, tokens, internal hostnames before upload.
• Pair with caching. A 200-page PDF is expensive every call; cached, it's a tenth the price on the second.

Related products.

Every Anthropic surface has its own page on this guide.