The Files API Portability Gap: Where It Works and the Inline Fallback

The Files API solves a real ergonomic problem: instead of base64-encoding the same 40 MB PDF into every request, you upload it once (POST /v1/files), get a file_id, and reference it in messages with "source": {"type": "file", "file_id": "..."}. Files persist until deleted, storage runs to 500 MB per file and 500 GB per organization, and all file operations are free — you pay input tokens only when file content is actually used in a message. It's a beta feature, gated by the anthropic-beta: files-api-2025-04-14 header (SDKs add it automatically on the beta.files namespace).

Where it works — and the Foundry fine print

Per Anthropic's documentation, the Files API is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry — but on Foundry only for Hosted-on-Anthropic deployments. Foundry offers Claude in two hosting versions, and against a Hosted-on-Azure deployment, Files API requests return 400 Bad Request by design. It is not available at all on Amazon Bedrock or Google Vertex AI. So a codebase that assumes file_id sources exist will break on two of the four third-party platforms, plus one of Foundry's two deployment flavors.

The practical consequence isn't just an error to catch. Without the Files API, every image and document must be delivered inline as base64 inside the request body — and inline payloads run into request-size ceilings: 32 MB on the Messages API, with Bedrock limiting payloads to 20 MB and Vertex to 30 MB. Large-document workloads that were comfortable with 500 MB uploads need chunking or preprocessing on the platforms that lack the endpoint.

Detecting availability at startup

You have two reasonable strategies, and the boring one is better: configure it, don't probe it. Availability is a static property of the platform you deployed against, so a per-platform capability flag in config is deterministic and free. If you do want a runtime check — say, your service ships to customer-controlled environments where the platform isn't known at build time — probe once at startup, not per request:

from anthropic import APIStatusError

def files_api_available(client) -> bool:
    try:
        client.beta.files.list(limit=1)
        return True
    except (APIStatusError, AttributeError):
        return False  # 400/404 on platforms without the Files API

USE_FILE_IDS = files_api_available(client)

Cache the answer for the process lifetime, and treat any failure as "unavailable" — the fallback path must work anyway.

The inline base64 fallback

Design the message-construction layer around one internal document type that renders two ways. When file_id sources are available, upload once, memoize the returned ID keyed by content hash, and emit {"type": "file", "file_id": ...} sources. Otherwise, read the bytes and emit {"type": "base64", "media_type": ..., "data": ...} sources inline. The surrounding document or image block is identical either way, so the fallback is invisible to prompt logic. Three details to get right:

Size-check before sending. On the inline path, enforce the platform's request ceiling (20 MB Bedrock, 30 MB Vertex) minus headroom for the rest of the payload, and split oversized documents upstream.
Don't leak IDs across platforms. A file_id minted on the Claude API means nothing on Claude Platform on AWS or Foundry — files are scoped to the workspace of the uploading key. Key your ID cache by platform + workspace.
Mind supported types. PDF and plain text map to document blocks; JPEG/PNG/GIF/WebP map to image blocks; .docx/.xlsx aren't supported in document blocks — convert to PDF or text before either path.

Rule of thumb: make base64 the code path you test hardest, even where the Files API exists. It's the only delivery mechanism that works on all four platforms, so it's your portability floor — file_id is an optimization on top.

One more caveat for regulated workloads

The Files API is beta and not eligible for Zero Data Retention (ZDR) — uploaded files persist until deleted by design. If your organization operates under ZDR or strict retention rules, the inline path may be the compliant default everywhere, which conveniently is also the portable one. Confirm specifics with your provider and Anthropic account team.

Where to go next

See the Files API reference article for endpoints and limits, and the platform workarounds in Bedrock and Vertex. The same adapter thinking applies to image sources and PDF sources.

Sources

← All articles