Claude Files API

The Claude Files API lets you upload a document once and reference it by a file ID across many subsequent API calls. Without it, if you want Claude to answer questions about a 50-page product catalogue you must send the full content on every request - paying for the same thousands of tokens repeatedly. With the Files API you upload once, receive a stable file_id, and include just that tiny ID in future requests. Claude reads the file from Anthropic storage rather than your application resending the bytes, cutting both latency and input token cost on every call that follows.

Files are stored up to 30 days and support PDF, plain text, and images. The file_id is stable - store it in your database and reuse it across sessions and across different users. When including a file in a message you add a document block with source type "file" and the file_id alongside your text question. This pattern is ideal for company policy documents, product catalogues, price lists, legal terms, and any reference document that many users query independently throughout the day.

The below example shows a home appliances retailer uploading their warranty terms document once at startup, then letting any number of customer service queries use that same uploaded file - no resending the document ever again.

It gives the following output,

Uploaded successfully.
file_id: file_011CNjxpvDdFEPVR2FpQXVq4
Reuse this ID for every warranty question - no re-upload needed.

It gives the following output,

Customer: My 3-year-old WareHome fridge compressor failed. Am I covered?
Agent:    Yes - refrigerators carry a 5-year compressor warranty, so your
          3-year-old fridge is fully covered. Call 1800-WAREHOME with your
          proof of purchase to raise a claim.

Customer: My kettle stopped working after 8 months. What should I do?
Agent:    Kettles have a 1-year warranty, so your 8-month-old kettle is
          covered. Visit any WareHome service centre with your receipt for
          a free repair or replacement.

Customer: I accidentally cracked the washing machine door glass. Covered?
Agent:    Physical damage is not covered under the standard warranty.
          If you purchased an Extended Warranty at the time of sale,
          accidental damage would be included - check your purchase receipt.

Customer: How long to receive a replacement if repair is not possible?
Agent:    WareHome delivers replacement units within 7 business days
          when a repair is not feasible.

Your uploaded files:
 - file_011CNjxpvDdFEPVR2FpQXVq4 | warranty_terms.txt

# 4 questions answered - warranty document uploaded to Anthropic only ONCE
# Each call sends only the tiny file_id, not 600+ tokens of document content
# At 1,000 daily queries this saves ~600,000 input tokens per day

Files API workflow for production: on application startup (or daily), upload your reference documents and store their file_ids in a config table in your database. When a customer query comes in, look up the relevant file_id (e.g. match product category to the right manual), and include it in the API call. Files expire after 30 days so schedule a weekly re-upload job. To delete a file before expiry call client.beta.files.delete(file_id=...). Use the Files API for any document over 1,000 tokens that more than one user will query - the crossover point where it saves money is roughly 3 queries per document per day.