anthropic-versionヘッダーとClaude APIのバージョン管理方針

anthropic-versionヘッダーとは何か

Claude APIへのリクエストには、anthropic-version というリクエストヘッダーを必ず付けます。API概要の認証ヘッダー表でも、anthropic-version は「必須: Yes」の行に入っています。値は anthropic-version: 2023-06-01 のように日付形式です。

curlや素のHTTPクライアントで直接APIを叩く場合は、このヘッダーを自分で指定します。公式クライアントSDK(Python / TypeScript等)なら、SDKが送信するので意識する場面はほとんどありません。公開されているPython SDKのクライアント実装でも、既定ヘッダーに "anthropic-version": "2023-06-01" が入っています。

このヘッダーが指すのは「APIの入出力フォーマットのバージョン」です。モデルの世代(Opus / Sonnet / Haikuなど)とは別軸の概念で、混同すると設定ミスにつながります。anthropic-version はAPIの通信仕様、モデル名はAIの世代。この対応で覚えておくと迷いません。

Anthropicの後方互換ポリシー

あるバージョンについて、次の2点は保持されます。

• 既存の入力パラメータ
• 既存の出力パラメータ

一方で、同じバージョン番号のまま次の変更が入る余地があります。

• 追加の入力パラメータ(オプション)を増やす
• 出力に追加の値を増やす
• 特定のエラー種別の発生条件を変える
• enum的な出力値に新しいバリアントを追加する(ストリーミングのイベント種別など)

つまり 2023-06-01 は「凍結されたスキーマ」ではありません。既存のキーが消えたり型が変わったりしない、という約束です。フィールドの追加やエラー条件の調整は、同一バージョン内で起こり得ます。

エラーのJSONも同じ扱いです。エラーページには、error オブジェクトの値は増え得ること、type の種類も時間とともに増え得ることが、このバージョン方針に沿った記述として書かれています。type を固定の列挙として決め打ちするコードは、この前提と相性が悪くなります。

バージョン履歴は実質2つしかない

anthropic-version の値として公式の履歴に載っているのは、次の2つだけです。

Claude APIは、後方互換な変更を同一バージョン内に入れていく方針です。実務で気にするのは「次のバージョンへの備え」より、「今のバージョンで何が保証されているか」になります。

2023-06-01でストリーミングはどう変わったか

2023-06-01 はストリーミングのレスポンス形式を作り直したバージョンです。補完テキストの返し方と、イベントの名前の付き方が変わりました。

SDKを使っていれば吸収されます。SSEを直接受信してテキストを結合している自作コードでは、全文が来る前提のロジックが 2023-06-01 では動きません。受け取った断片を上書きせず、連結する実装が必要です。

古いバージョンのまま使い続けるとどうなるか

公式の履歴ページには、最新バージョンの使用を推奨すること、以前のバージョンは非推奨(deprecated)扱いで新規ユーザーには利用できないことがあることが書かれています。つまり 2023-01-01 が、新しく作ったアカウントで受け付けられない可能性があります。

既存のコードが 2023-01-01 を指定している場合、いつまで動くかを示す日付は履歴ページにありません。2023-06-01 へ揃えると、この不確かさを抱えずに済みます。

同じ日付でも、クラウドごとに名前と置き場所が違う

Claude APIを直接叩く場合は、ヘッダーに anthropic-version: 2023-06-01 を付けます。ところがクラウド経由では、同じ概念が別の名前で、別の場所に置かれます。クラウド別の呼び出し例を引き写すとき、ここで取り違えが起きやすくなります。

Vertex側の値は日付が違い、先頭に vertex- が付きます。Anthropic APIの 2023-06-01 をそのまま入れると、別の値になる点に注意が必要です。Bedrockの旧統合も同様です。

anthropic-versionとツールバージョンは別物

紛らわしいのが、ツール名末尾の日付です。たとえばWeb検索ツールには web_search_20250305、web_search_20260209、web_search_20260318 と、日付違いの名前が並んでいます。一方、anthropic-version は 2023-06-01 のままです。

ツール名の日付は、個々のツール定義のバージョンです。リクエスト全体の通信フォーマットを指す anthropic-version とは、管理の階層が違います。ツールのバージョニングの詳細はClaude APIツールのバージョン管理ガイドにまとめています。

• anthropic-version ヘッダー: リクエスト全体の通信フォーマット(現行は 2023-06-01)
• ツール名の _YYYYMMDD サフィックス: そのツール固有の入出力スキーマ(ツールごとに独立して増える)

片方を更新しても、もう片方には影響しません。エラーログに日付表記が混在すると取り違えやすいので、どちらを指しているかをコードコメントに残しておくと保守が楽です。

anthropic-versionとanthropic-betaは別ヘッダー

もう1つ混同しやすいのが anthropic-beta ヘッダーです。役割は別で、片方は通信フォーマットを固定し、もう片方は実験的機能を選びます。

両方を同時に送るリクエストは珍しくありません。コンテキスト編集のベータを試すcurlは次の形です。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: context-management-2025-06-27" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-5-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello, Claude"}]}'

anthropic-beta は常に任意というわけではありません。/v1/agents、/v1/sessions、/v1/environments は managed-agents-2026-04-01、/v1/tunnels は mcp-tunnels-2026-06-22、/v1/memory_stores とその配下は agent-memory-2026-07-22 を、生のHTTPで呼ぶときは毎回付けます。SDKの client.beta なら自動で付きます。

メモリストアのエンドポイントでは、agent-memory-2026-07-22 が managed-agents-2026-04-01 に置き換わります。両方を同じリクエストに入れると 400 エラーになります。

複数のベータはカンマ区切りで1本のヘッダーに書けます。同じ anthropic-beta ヘッダーを複数回送る書き方も、同じ意味で受け付けられます。

400エラーが返ったときの切り分け

anthropic-version が絡む失敗に、専用のエラーコードはありません。エラー一覧の 400 invalid_request_error は、リクエストの形式または内容に問題があるときの種別で、他の4XXにも使われると書かれています。ヘッダーが原因かどうかは、メッセージとリクエスト内容から自分で切り分けます。

Claude APIのエラーハンドリング設計では、ヘッダー起因を含むエラー種別ごとの対処をまとめています。

新しいモデルが出てもヘッダーは変わらない

新しいモデル世代が出ても、anthropic-version の値は変わりません。公式のサンプルでは、Claude Opus 5.5(claude-opus-5-5)を呼ぶcurlも、anthropic-version: 2023-06-01 のままです。

新しいコンテンツブロックや出力値は、後方互換ポリシーが許容する「enum的な出力値への新しいバリアント追加」の枠で入ります。モデルのアップグレードとAPIバージョンの更新は、別々のタイミングで動く独立した軸です。リリースノートを読むときは、モデル名の更新を見て、ヘッダーの書き換えが要ると早合点しないようにします。

実装で気を付けること

curlのように自分でHTTPリクエストを組み立てるツールでは、ヘッダーの記述漏れがそのまま障害につながります。レビューのチェック項目に「anthropic-version を静的な文字列で複数箇所に書いていないか」を加えておくと、将来の切り替え作業が1か所で済みます。

最小のリクエストは次の形です。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-5-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

API概要の認証ヘッダー表では、Authorization: Bearer <token> が先に挙がり、x-api-key は従来のAPIキー用の代替として「still supported」と注記されています。上のcurl例は後者の書き方です。

このバージョン管理方針をどう読むか

日付ベースの識別子は「いつ時点の仕様か」が一目で分かります。Claude APIは2023-06-01以降、バージョン識別子を切っていません。利用者にとっては、バージョン追従のメンテナンスコストがほぼ発生しない運用です。

そのぶん、変更の追跡先が分かれます。破壊的でない変更は同一バージョンに入るので、anthropic-version を眺めても変化に気づけません。エラーの種別や出力値の追加は、公式のリリースノートで追うことになります。

まとめ

anthropic-version はClaude APIの通信フォーマットを指定する必須ヘッダーで、公式の履歴にある値は 2023-01-01 と 2023-06-01 の2つです。Vertexでは vertex-2023-10-16、Bedrockの旧統合では bedrock-2023-05-31 と、面によって名前と置き場所が変わります。

SDK利用者が意識する場面は少ないものの、curlで直接叩くコードと、ストリーミングを自作パースしているコードは、2023-06-01 の差分方式とヘッダーの置き場所を確かめておくと安全です。