2026年10月21日、Claude APIに新しいAPIバージョン 2026-10-21 が加わった。2023-06-01 以来の更新で、temperature を送るだけで400エラーになる。複数チームがSDKを使い、社内ゲートウェイや監視基盤がヘッダーを読んでいるエンタープライズでは、各チームが個別にSDKを上げるだけでは安全に移行できない。本稿は公式の移行ガイドに沿って、基盤チームが先に押さえる変更点と段階移行の設計を整理する。
2026-10-21でMessages APIの何が壊れるのか
2026-10-21ではtemperature等の送信と、assistantへのdocument配置が400エラーになります。
Messages API(POST /v1/messages)、トークンカウント、Message Batchの各リクエストに次の3つが適用される。
- サンプリングパラメータの除去:
temperature、top_p、top_kは既定値でも400になる。最新メジャーのSDKとCLIからはこの3つの引数自体がなくなった - assistantメッセージ内のdocumentブロック: 400になる。documentはuserメッセージで送る。web fetchツール結果のようにブロックの内側にあるdocumentは従来どおり受理される
- userメッセージのtextブロックに付けたcitations: 空でない
citations配列は400になる。assistant側のcitationsと、documentや検索結果の"citations": {"enabled": true}は有効なまま
注意すべきは挙動の変化だ。送信をやめた場合の値は既定値(temperature は1.0)になる。Claude 4.7以降のように既定値しか受け付けないモデルは変わらないが、Claude Sonnet 4.6のように別の値を受け付けるモデルで出力の安定化のために temperature を下げていた呼び出しは、その効果を失う。代替設定は用意されていない。
APIキーのヘッダー変更でゲートウェイは何を直すのか
新SDKはAPIキーをAuthorization: Bearerで送るため、X-Api-Keyを読むゲートウェイは修正が必要です。
SDKとCLIは、キーを Authorization: Bearer <key> で送る。Claude API側はどちらのヘッダーのキーも受理するため、API自体は止まらない。壊れるのは自社側の層だ。
X-Api-Keyを読んでチーム識別や課金按分をしているプロキシ・LLMゲートウェイX-Api-Keyをマスクしているログフィルタ、監視、テストスタブ- リクエスト単位で
X-Api-Keyを上書き・削除していたコード。新SDKでは上書きしても両方のキーが送られ、削除しても効かない
一方、SDKクライアントが保持する資格情報は1つになった。APIキーと認証トークンが同じヘッダーを使うためで、Python SDKではコンストラクタに2つ以上渡すと ValueError になる。ゲートウェイ側は Authorization と X-Api-Key の両方を読む期間を設けてから、X-Api-Key 依存を外す順序が安全だ。構成の考え方はLLMゲートウェイの設計も参考になる。
Admin APIのフィールド名変更はどこに影響するのか
Admin APIの応答からrolesなど旧フィールド名が消えるため、棚卸しや集計コードの修正が必要です。
2026-10-21の応答からは旧名が消える。基盤チームのメンバー管理・コスト配賦の自動化に直撃する。
| 対象 | 旧名 | 新名 |
|---|---|---|
| RBACグループ | roles | role_ids |
| RBACグループメンバー | group_id | rbac_group_id |
| RBACロール | name | display_name |
| レート制限 | group_type | group.type |
| APIキー | workspace_id | scope |
| Analytics(ユーザー別) | actor.email | actor.email_address |
| Analytics(サマリー) | summaries | data |
最も落とし穴が大きいのはAPIキーだ。旧版の workspace_id が null だったキーは「Defaultワークスペース」か「全ワークスペース共通」かの区別がつかなかった。新版では scope.workspace_id に実IDが入り、全ワークスペース共通キーは scope が {"type": "organization"} になる。null をDefault扱いしていた棚卸しスクリプトは、scope.workspace_id をDefaultワークスペースのIDと比較する形に書き換える。ワークスペース統制の全体像はワークスペース管理とWIFで扱っている。
どう段階移行を設計するべきか
移行は基盤層の先行修正、SDK更新、チーム別検証の順に進め、旧版に残す例外を管理します。
APIバージョンはSDKのメジャーバージョンと連動する。Python 2.0.0、TypeScript 1.0.0、Go 2.0.0(モジュールパスは /v2)、Java 3.0.0、ant CLI 2.0.0 などが初めて 2026-10-21 を既定で送る。SDKを使わない場合は anthropic-version ヘッダーを自分で指定する。
- インベントリ: SDKのバージョン、
temperature系の送信箇所、X-Api-Key依存、Admin API利用スクリプトを全チームから洗い出す - 基盤層の先行対応: ゲートウェイとログ基盤を両ヘッダー対応にし、Admin API連携を新フィールド名に切り替える
- 例外の明示: 非既定の
temperatureが必須の呼び出しは、そのリクエストだけ2023-06-01に残せる。例外はチケットと期限で管理する - Amazon Bedrockの扱い:
2026-10-21はClaude 4.7以降のモデルでのみ利用できる。旧モデルを呼ぶ経路は現行のSDKとバージョンを維持し、先にモデルを移す - テスト: 本番切替前に
2026-10-21で統合テストを回す
旧版の廃止期限は、確認した公式資料に記載がなかった。期限が公表されるまでは、例外を放置せず棚卸しを続ける運用が妥当だ。全社規模のAI基盤変更管理は、Kuuの大企業向けAI変革プログラムRDEでも支援している。
参考
まとめ
壊れるのは、サンプリング引数の送信、X-Api-Key 依存、Admin APIの旧フィールド名の3点に集約できる。基盤チームが先に両ヘッダー対応と新フィールド対応を済ませ、各チームのSDK更新を安全に受け止める順序を取れば、全社移行の手戻りは小さくなる。移行計画の設計や統制の整備は、RDEからお問い合わせください。
