The anthropic-beta Header: Which Platforms Pass It Through

Anthropic ships pre-release API features behind the anthropic-beta header: you add a dated flag such as compact-2026-01-12 or context-management-2025-06-27 to the request, and the API enables that behavior for you. It is a clean mechanism — until you deploy the same code on a platform that does not carry the header through. Then the feature silently isn't there, or the extra request fields it unlocked start failing validation, and the bug report says "works on the Claude API, breaks on Bedrock."

Where the header works

Claude API (1P). The native home of the mechanism. SDKs often set the header for you when you use a beta namespace — for example, the Files API's files-api-2025-04-14 flag is added automatically on client.beta.files calls.

Claude Platform on AWS. Anthropic's docs are explicit: beta features pass through with the standard anthropic-beta header, same as the Claude API. A useful side detail for IAM administrators: beta variants of a route do not require a separate IAM action — the same action covers the GA and beta forms.

Microsoft Foundry. Microsoft's own Claude documentation names specific beta headers as supported — fine-grained-tool-streaming-2025-05-14 and context-management-2025-06-27 among them — so the header travels through the Foundry endpoint to Claude. Bear in mind that much of Foundry's Claude feature surface is itself flagged beta, and some features are only available on Hosted-on-Anthropic deployments; an Azure-hosted deployment returns 400 Bad Request by design for features it does not host, header or no header.

Google Vertex AI. Beta-gated capabilities such as compaction and context editing are listed as available for Claude on Vertex, so beta opt-ins do reach the model there. Because Vertex reshapes the request (model in the URL, anthropic_version in the body), let the AnthropicVertex SDK client handle beta flags rather than hand-rolling headers, and check Google's Claude pages for the current mechanism if you must send raw HTTP.

Where it does not: legacy Bedrock

Amazon Bedrock's legacy InvokeModel/Converse surface does not support the anthropic-beta header — Anthropic's Claude Platform on AWS documentation states this contrast directly. The legacy surface has its own body-level versioning ("anthropic_version": "bedrock-2023-05-31") and its own feature schedule set by AWS. If your beta-dependent code path runs against that surface, the opt-in never reaches Claude.

What that looks like in practice:

Silent absence. Features that merely change behavior (for example, an overflow-handling opt-in) simply don't activate. Output differs between platforms with no error to catch.
Validation errors. Features that add request fields (such as context_management blocks) fail, because the body contains parameters the non-beta schema does not accept.
Missing endpoints. Beta endpoints like the Files API do not exist on Bedrock at all — no header could help, because the availability gap is at the platform level, not the header level.

Rule of thumb: the header being deliverable is necessary but not sufficient. A beta flag only works where the underlying feature exists on that platform. Check the availability matrix first, then worry about the header.

Gating beta features by platform

The robust pattern is a small capability map next to your provider factory, keyed by the same PLATFORM setting, consulted before any beta-dependent request is built:

CAPABILITIES = {
    "1p":      {"compaction": True,  "files_api": True},
    "aws":     {"compaction": True,  "files_api": True},   # P-AWS: 1P parity
    "bedrock": {"compaction": True,  "files_api": False},  # current surface
    "vertex":  {"compaction": True,  "files_api": False},
    "foundry": {"compaction": True,  "files_api": True},   # beta on Foundry
}

def supports(platform: str, feature: str) -> bool:
    return CAPABILITIES.get(platform, {}).get(feature, False)

Populate the map from official documentation rather than trial and error, keep it in one file, and make the fallback path explicit (skip the feature, or route that request class to a platform that supports it). This turns "works on my platform" bugs into a code-reviewable table.

Where to go next

If legacy Bedrock is the thing holding your beta features back, upgrading to the current Mantle surface is the structural fix. For the full feature-by-platform picture, see the feature matrix.

Sources

← All articles