Migrasi ke versi API 2026-10-21

Panduan ini mencantumkan perubahan kode untuk berpindah dari versi API 2023-06-01 ke 2026-10-21. Langkah-langkah peningkatan menjelaskan apa yang harus dilakukan, secara berurutan.

Langkah-langkah peningkatan

1. 1

   Beralih ke 2026-10-21

   Jika Anda menggunakan SDK, permintaan Anda menggunakan versi API yang berlaku saat versi mayor SDK Anda dirilis. Versi yang ditampilkan untuk bahasa Anda adalah yang pertama menggunakan 2026-10-21, jadi tingkatkan ke versi tersebut. Jika Anda memanggil API tanpa SDK, atur header anthropic-version ke 2026-10-21.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   Tingkatkan paket anthropic ke versi 2.0.0.

   Rilis peningkatan ini bersama dengan perbaikan Anda dari langkah berikutnya.

2. 2

   Perbarui kode Anda untuk perubahan yang merusak kompatibilitas

   Tinjau perubahan yang merusak kompatibilitas, dan perbarui kode Anda untuk setiap perubahan yang memengaruhi Anda. Lakukan juga perubahan kode yang diperlukan oleh versi SDK atau CLI yang baru.

3. 3

   Uji terhadap 2026-10-21

   Uji integrasi Anda terhadap 2026-10-21 sebelum Anda merilis.

Perubahan yang merusak kompatibilitas

Messages API

Perubahan ini berlaku untuk permintaan ke Messages API (POST /v1/messages), untuk penghitungan token, dan untuk setiap permintaan dalam Message Batch yang dibuat dengan 2026-10-21.

Blok dokumen dalam pesan assistant mengembalikan error

Memengaruhi Anda jika Anda mengirim blok document secara langsung dalam pesan assistant.

Di 2026-10-21, permintaan yang menempatkan blok document secara langsung dalam pesan assistant mengembalikan error 400. Kirim dokumen dalam pesan user sebagai gantinya. Dokumen yang bersarang di dalam blok lain, seperti hasil alat web fetch yang dikembalikan Claude, tetap diterima.

Sitasi dalam pesan user mengembalikan error

Memengaruhi Anda jika Anda mengirim citations pada blok text dalam pesan user, termasuk di dalam blok search_result.

Di 2026-10-21, permintaan yang mengirim blok text dengan array citations yang tidak kosong dalam pesan user mengembalikan error 400. Hapus citations dari blok-blok tersebut. Sitasi pada blok text dalam pesan assistant, seperti balasan Claude sebelumnya yang Anda kirim kembali, tetap diterima, begitu pula pengaturan "citations": {"enabled": true} pada dokumen dan hasil pencarian.

Parameter sampling dihapus

Memengaruhi Anda jika Anda mengirim temperature, top_p, atau top_k dalam permintaan Messages atau permintaan Message Batch.

Di 2026-10-21, permintaan yang mengirim temperature, top_p, atau top_k mengembalikan error 400, bahkan pada nilai default parameter tersebut.

Hapus ketiga parameter tersebut dari permintaan Anda.

Sejak versi mayor terbaru, SDK dan CLI tidak lagi memiliki ketiga parameter tersebut.

Tanpa parameter ini, permintaan melakukan sampling dengan nilai default-nya, termasuk temperature sebesar 1.0, sama seperti permintaan 2023-06-01 yang tidak menyertakannya. Model yang sudah hanya menerima nilai default, seperti model Claude 4.7 dan yang lebih baru, melakukan sampling seperti sebelumnya. Pada model yang menerima nilai lain, seperti Claude Sonnet 4.6, permintaan yang menurunkan temperature untuk output yang lebih konsisten kehilangan efek tersebut. Tidak ada pengaturan lain yang menggantikannya. Jika suatu permintaan bergantung pada nilai non-default, hentikan pengiriman parameter tersebut, atau pertahankan permintaan itu pada 2023-06-01.

Admin API dan Claude Enterprise Analytics API

Memengaruhi Anda jika kode Anda membaca field respons Admin API atau Claude Enterprise Analytics API dalam tabel berikut.

Di 2026-10-21, respons dari Admin API dan Claude Enterprise Analytics API tidak lagi menyertakan nama lama dari field yang diganti namanya. Gunakan nama baru sebagai gantinya.

Admin API:

Claude Enterprise Analytics API:

Parameter kueri group_type pada endpoint list batas laju dan filter workspace_id pada endpoint list kunci API tidak berubah.

workspace_id pada kunci API

Memengaruhi Anda jika kode Anda membaca workspace_id pada kunci API.

Di 2023-06-01, workspace_id dari kunci API adalah ID workspace tempat kunci tersebut terikat, atau null untuk kunci yang terikat ke Default Workspace dan untuk kunci yang tidak terikat ke satu workspace (kunci semua workspace).

Di 2026-10-21, workspace_id dihapus. Baca scope sebagai gantinya: untuk kunci yang terikat ke workspace, termasuk Default Workspace, scope.workspace_id adalah ID sebenarnya dari workspace tersebut, dan kunci semua workspace memiliki scope berupa {"type": "organization"}, tanpa workspace_id.

Jika kode Anda memperlakukan workspace_id yang bernilai null sebagai Default Workspace, bandingkan scope.workspace_id dengan ID Default Workspace Anda sebagai gantinya. Untuk menemukan ID tersebut, panggil List Workspaces dengan include_default=true dan ambil workspace bernama "Default".

Perubahan SDK dan CLI

Versi SDK dan CLI sebelumnya mengirim anthropic-version: 2023-06-01 pada setiap permintaan. Versi di bawah Beralih ke 2026-10-21 mengirim 2026-10-21. Perubahan dalam Perubahan yang merusak kompatibilitas juga berlaku untuk versi tersebut: parameter yang dihapus dan nama field lama juga hilang dari tipe SDK serta dari flag dan output CLI.

Versi API di Amazon Bedrock dan Google Cloud

Klien SDK untuk Google Cloud's Agent Platform menyebutkan versi di body permintaan, bukan di header. Klien ini mengirim anthropic_version: 2026-10-21, sedangkan versi sebelumnya mengirim vertex-2023-10-16, dan tidak mengirim header anthropic-version.

Klien Amazon Bedrock melakukan hal yang sama. Klien ini mengirim anthropic_version: 2026-10-21, sedangkan versi sebelumnya mengirim bedrock-2023-05-31, dan tidak mengirim header anthropic-version. Model yang lebih lama dari Claude Opus 4.7 belum mendukung versi API 2026-10-21 di Bedrock, dan permintaan yang menyebutkannya mungkin mendapatkan error 400. Jika Anda menggunakan salah satunya, tetaplah pada versi SDK sebelumnya untuk saat ini, atau tingkatkan dan kirim bedrock-2023-05-31 sendiri.

MessageParam adalah union dengan satu tipe per peran

Pada versi sebelumnya, MessageParam adalah satu tipe untuk setiap peran. Setiap peran sekarang memiliki tipenya sendiri: UserMessageParam, AssistantMessageParam, dan SystemMessageParam. BetaMessageParam dipecah dengan cara yang sama, menjadi BetaUserMessageParam, BetaAssistantMessageParam, dan BetaSystemMessageParam. Permintaan yang dikirim SDK memiliki field dan nilai yang sama seperti sebelumnya.

# Sebelum
message = MessageParam(role="user", content="Hello")

# Sesudah
message: MessageParam = {"role": "user", "content": "Hello"}

# Sebelum
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# Sesudah
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

Enum bernilai tunggal menjadi konstanta

Ini memengaruhi SDK C#, Go, Java, PHP, dan Ruby serta satu flag CLI. Pada versi sebelumnya, field wajib yang hanya dapat menampung satu nilai memiliki tipe enum tersendiri dengan satu anggota. Field-field ini sekarang menjadi konstanta, dan tipe enum tersebut telah dihapus. JSON yang dikirim dan dibaca oleh SDK tetap sama.

Compaction sisi klien dihapus dari tool runner

Ini memengaruhi SDK TypeScript dan Ruby. "Client-side compaction" (pemadatan sisi klien) di tool runner telah dihapus dan digantikan oleh compaction sisi server, yang merangkum percakapan di dalam API alih-alih dengan request tambahan dari klien.

// Sebelum
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// Sesudah
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

Ambang batas pemicu harus setidaknya 50.000 token. Lihat compaction untuk opsi lainnya (pause_after_compaction, instructions kustom).

Text Completions dihapus

Text Completions API lama dihapus dari SDK TypeScript, Go, Java, dan Ruby serta dari CLI. Model dan fitur yang lebih baru tidak mendukungnya. Gunakan Messages API sebagai gantinya.

# Sebelum
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# Sesudah
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

betas dihapus dari metode Models non-beta

Metode Models non-beta tidak lagi menerima betas, dan perintah ant models tidak lagi menerima --beta. Untuk mengirim header beta, panggil metode yang sama pada client.beta.models, atau ant beta:models di CLI. Di SDK, metode-metode tersebut mengembalikan BetaModelInfo sedangkan metode non-beta mengembalikan ModelInfo.

# Sebelum
page = client.models.list(betas=[beta])

# Sesudah
page = client.beta.models.list(betas=[beta])

Kunci API dikirim sebagai Authorization: Bearer

SDK dan CLI mengirim kunci API Anda sebagai Authorization: Bearer <key> alih-alih di header X-Api-Key, jadi ubah proxy atau gateway apa pun yang membaca atau mengatur X-Api-Key agar menggunakan Authorization, atau kirim sendiri kunci tersebut di X-Api-Key. Claude API menerima kunci di salah satu header tersebut, sehingga program yang berkomunikasi langsung dengan API tidak memerlukan perubahan.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Jika proxy atau gateway membaca X-Api-Key

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

Jika Anda mengatur atau menghapus X-Api-Key pada request

Ini memengaruhi SDK Python, TypeScript, Go, PHP, dan Ruby.

Jika Anda menghapus X-Api-Key agar request hanya mengirim auth token, hapus kode tersebut alih-alih mengubahnya, karena menghapus Authorization akan menghapus token. Sebuah klien memegang satu kredensial, jadi pastikan kredensial tersebut adalah token: jika tidak ada yang diteruskan dalam kode dan ANTHROPIC_API_KEY serta ANTHROPIC_AUTH_TOKEN keduanya diatur, klien menggunakan kunci.

Klien memegang satu kredensial

Kunci API dan token autentikasi kini berbagi satu header, sehingga klien SDK memegang satu kredensial. Jika tidak ada yang diteruskan dalam kode, klien mengikuti urutan prioritas kredensial.

client = Anthropic(api_key=key, auth_token=token)

# Sebelum: mengirim `X-Api-Key: <key>` dan `Authorization: Bearer <token>`
# Sesudah:  memunculkan `ValueError`

Perubahan pada satu SDK atau CLI

Masing-masing perubahan ini memengaruhi satu SDK atau CLI.

# Sebelum
ant --api-key "$KEY" models list

# Sesudah, dari environment
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Sesudah, dari secret manager
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

Lisensinya adalah Apache 2.0

Mulai dari versi-versi ini, SDK dan CLI dilisensikan di bawah Apache License, Version 2.0. Versi sebelumnya tetap di bawah MIT License. Tidak ada perubahan kode yang diperlukan. Jika Anda melacak lisensi dependensi Anda, perbarui entri-entrinya.

• TypeScript: Paket platform (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk, dan @anthropic-ai/google-cloud-sdk) berganti lisensi dalam rilis 1.0.0 masing-masing.
• C#: Paket lainnya (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud, dan Anthropic.Mcp) berganti lisensi dalam rilis 1.0.0 masing-masing.
• Java: Perubahan ini mencakup setiap artefak com.anthropic.