Claude API 2026-10-21 Sürümüne Geçiş Rehberi: Kırılma Değişiklikleri, Yeni SDK'lar ve Kontrol Listesi

Claude API'yi doğrudan kullanan herkesin her istekte gönderdiği küçük bir başlık var: anthropic-version. Yıllardır bu başlığın değeri neredeyse herkes için aynıydı: 2023-06-01. 21 Ekim 2026'da Anthropic yeni bir API sürümü yayımladı: 2026-10-21. Aynı gün Python, TypeScript, C#, Go, Java, PHP ve Ruby SDK'larının yeni major sürümleriyle ant CLI 2.0.0 da çıktı. Bu sürümler varsayılan olarak yeni API sürümünü gönderiyor.

Resmi sürüm geçmişine bakınca değişikliğin büyüklüğü anlaşılıyor: listede yalnızca üç sürüm var. 2023-01-01 ilk sürümdü, 2023-06-01 akış (streaming) formatını değiştirdi, şimdi de 2026-10-21 geldi. Yani üç yılı aşkın süredir ilk kez API sözleşmesinde kırılma değişikliği yapan bir sürümle karşı karşıyayız. Paket yöneticiniz SDK'yı bir sonraki upgrade'de yeni major sürüme taşırsa, kodunuz farkında olmadan yeni sözleşmeye geçebilir.

Bu yazıda resmi geçiş rehberini (Migrating to API version 2026-10-21) ve sürüm notlarını temel alarak şunları anlatıyorum: anthropic-version başlığı ne işe yarar, Messages API'de neler kırıldı, temperature parametresine ne oldu, Admin API'de hangi alanların adı değişti, SDK'larda MessageParam ve kimlik doğrulama tarafında neler değişti, proxy/gateway kullananlar neye dikkat etmeli ve Claude Code'un /claude-api api-version komutu bu geçişte nasıl yardımcı olur. Sonunda adım adım bir geçiş akışı, sorun giderme listesi ve SSS bulacaksınız.

anthropic-version Başlığı Nedir, Neden Önemli?

Claude API'ye yapılan her istek bir anthropic-version başlığı taşımak zorunda. SDK kullanıyorsanız bu başlığı SDK sizin yerinize ekler; ham HTTP ile çağırıyorsanız kendiniz yazarsınız. Resmi "Versions" sayfasına göre Anthropic, belirli bir API sürümü için şunları korur:

• Mevcut girdi parametreleri
• Mevcut çıktı parametreleri

Buna karşılık aynı sürüm içinde şunları yapabilir: yeni isteğe bağlı girdiler eklemek, çıktıya yeni değerler eklemek, belirli hata türlerinin koşullarını değiştirmek ve akış olay türleri gibi enum benzeri çıktılara yeni varyantlar eklemek. Kısacası, dokümante edildiği gibi kullandığınız sürece mevcut sürüm sizi kırmaz. Bir parametreyi kaldırmak veya bir alanın adını değiştirmek gibi gerçekten kırıcı değişiklikler ise yeni bir sürüm numarası gerektirir. 2026-10-21 tam olarak budur: geriye dönük uyumsuz değişikliklerin toplandığı yeni sözleşme.

Pratik sonuç şu: hangi sürümle konuştuğunuzu başlık belirler. Eski SDK sürümleri her isteğe anthropic-version: 2023-06-01 ekliyordu. Yeni major sürümler (Python 2.0.0, TypeScript 1.0.0 vb.) 2026-10-21 gönderiyor; buna Amazon Bedrock ve Google Cloud istemcileri de dahil. Dolayısıyla "SDK'yı güncelledim" demek, artık "API sürümünü de değiştirdim" demek.

2026-10-21 ile Neler Değişti? Hızlı Özet

Değişiklikleri iki gruba ayırmak işinizi kolaylaştırır. Birinci grup API sürümünün kendisinden gelir ve ham HTTP kullananları da etkiler. İkinci grup yeni SDK/CLI sürümlerinden gelir; bunlar API sürümünden bağımsızdır ve yalnızca SDK veya ant kullananları ilgilendirir.

Değişiklik	Kaynağı	Kimi etkiler?
temperature, top_p, top_k kaldırıldı (gönderilirse 400)	API sürümü	Bu parametreleri gönderen herkes
assistant mesajında doğrudan document bloğu → 400	API sürümü	Belgeleri asistan mesajına koyanlar
user mesajında dolu citations dizisi → 400	API sürümü	Alıntıları kullanıcı mesajında geri gönderenler
Admin API ve Enterprise Analytics API'de eski alan adları kalktı	API sürümü	Yönetim/raporlama otomasyonu yazanlar
MessageParam rol başına ayrı tiplerin birleşimi (union) oldu	SDK	Tüm SDK kullanıcıları (çoğunlukla tip düzeyinde)
API anahtarı Authorization: Bearer ile gönderiliyor	SDK ve CLI	X-Api-Key okuyan proxy/gateway/middleware sahipleri
Bir istemci tek kimlik bilgisi tutar	SDK	Hem anahtar hem token veren kodlar
Text Completions kaldırıldı	SDK ve CLI	TypeScript, Go, Java, Ruby ve CLI'da eski Completions kullananlar
Beta olmayan Models metotlarından betas kalktı	SDK ve CLI	Model listesini beta başlığıyla çekenler
Tool runner'da istemci taraflı compaction kalktı	SDK	TypeScript ve Ruby tool runner kullanıcıları
ant CLI'dan --api-key ve --auth-token kalktı	CLI	Betiklerde anahtarı bayrakla verenler
Lisans MIT'ten Apache 2.0'a geçti	SDK ve CLI	Bağımlılık lisanslarını takip edenler

Hangi SDK Sürümüne Yükseltmeliyim?

Geçiş rehberi her dil için 2026-10-21'i kullanan ilk sürümü listeliyor. Bu sürümlere (veya sonrasına) yükseldiğinizde SDK yeni API sürümünü gönderir.

Dil / Araç	Paket	2026-10-21'i gönderen ilk sürüm	Dikkat
Python	anthropic	2.0.0	—
TypeScript	@anthropic-ai/sdk	1.0.0	Bedrock/Vertex/Foundry/AWS/Google Cloud paketlerini de aynı anda v1'e taşıyın
C#	Anthropic	13.0.0	—
Go	github.com/anthropics/anthropic-sdk-go/v2	2.0.0	Import yolu /v2 ile değişir; Go 1.25+ gerekir
Java	com.anthropic:anthropic-java	3.0.0	—
PHP	anthropic-ai/sdk	1.0.0	composer update yetmez, composer require gerekir
Ruby	anthropic gem	2.0.0	—
CLI	ant	2.0.0	go install yolu /v2 ile değişir

Tablodaki üç tuzak üzerinde biraz durmak gerekiyor:

• TypeScript platform paketleri: @anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk ve @anthropic-ai/google-cloud-sdk paketlerinin v1'i, @anthropic-ai/sdk'nın v1'ini istiyor; eski sürümleri ise 1'in altını. Ana SDK'yı yükseltip bunları unutursanız paket yöneticiniz eski platform paketi için ikinci, eski bir @anthropic-ai/sdk kopyası kurar.
• Go modül yolu: Go, major sürümü 2 ve üzeri olan modüllerin yolunun sürümle bitmesini şart koşar. Bu yüzden her github.com/anthropics/anthropic-sdk-go importunu (ve .../option gibi alt paketleri) github.com/anthropics/anthropic-sdk-go/v2 ile başlayacak şekilde değiştirmeniz gerekiyor. CLI için de durum aynı: eski go install yolu hiçbir uyarı vermeden v1'in son sürümünü kurmaya devam ediyor.
• PHP: composer update mevcut sürüm kısıtınızın içinde kalır; 1.0.0'a geçmek için composer require "anthropic-ai/sdk" çalıştırmanız gerekir.

# Python
pip install --upgrade "anthropic>=2.0.0"

# TypeScript (platform paketi kullanıyorsanız onu da aynı anda)
npm install @anthropic-ai/sdk@^1.0.0 @anthropic-ai/bedrock-sdk@^1.0.0

# Go: önce importları /v2'ye çevirin, sonra
go get github.com/anthropics/anthropic-sdk-go/v2

# PHP
composer require "anthropic-ai/sdk"

# ant CLI (go install ile kuruyorsanız)
# Önce
go install 'github.com/anthropics/anthropic-cli/cmd/ant@latest'
# Sonra
go install 'github.com/anthropics/anthropic-cli/v2/cmd/ant@latest'

SDK kullanmıyorsanız tek yapmanız gereken başlığı değiştirmek. Resmi rehberdeki cURL örneği şöyle:

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

Dikkat ederseniz ham HTTP örneğinde anahtar hâlâ x-api-key ile gidiyor. Rehber, Claude API'nin anahtarı her iki başlıkta da kabul ettiğini söylüyor; Authorization: Bearer geçişi API'nin değil SDK'ların davranış değişikliği.

Amazon Bedrock Kullananlar İçin Önemli Uyarı

Sürüm sayfasına göre 2026-10-21; Claude API, Claude Platform on AWS, Claude Models on Google Cloud (hem Anthropic hem Google tarafından yönetilen), Microsoft Foundry ve Amazon Bedrock'ta mevcut. Ancak Bedrock'ta bir kısıt var: yeni sürüm yalnızca Claude 4.7 ve sonraki modeller için kullanılabiliyor.

Bedrock üzerinde Opus 4.6 ve öncesi gibi eski bir modeli çağırıyorsanız rehberin önerisi net: bugün kullandığınız SDK sürümünde kalın ya da API sürümünü kendiniz ayarlıyorsanız bugün gönderdiğiniz değeri göndermeye devam edin. Bu çağrıları 2026-10-21'e taşımak için önce Claude 4.7 veya sonraki bir modele geçmeniz gerekiyor. Yani Bedrock'ta eski modele bağlı bir üretim sisteminiz varsa, SDK yükseltmesini model geçişiyle birlikte planlamalısınız.

Messages API'deki Kırılma Değişiklikleri

Bu değişiklikler Messages API (POST /v1/messages), token sayma uç noktası ve 2026-10-21 ile oluşturulan bir Message Batch içindeki her istek için geçerli.

temperature, top_p ve top_k Neden Kaldırıldı, Yerine Ne Var?

En geniş etkili değişiklik bu. 2026-10-21'de temperature, top_p veya top_k gönderen bir istek, parametrenin varsayılan değeriyle bile gönderilse 400 hatası döner. Sürüm sayfası bunun her model için geçerli olduğunu belirtiyor. En yeni SDK ve CLI sürümlerinde bu üç parametre artık hiç yok; yani yükselttiğinizde bunları kullanan kod derleme veya tip kontrolü aşamasında da sorun çıkarır.

Parametreleri göndermediğinizde istek varsayılanlarla örneklenir; bu da 1.0 değerinde bir temperature demek. Bu, parametreleri hiç göndermeyen bir 2023-06-01 isteğiyle aynı davranış. Peki kimin çıktısı değişir?

• Claude 4.7 ve sonraki modeller: Rehbere göre bu modeller zaten yalnızca varsayılan değerleri kabul ediyor, dolayısıyla örnekleme davranışları değişmiyor. Parametreyi kodunuzdan silmeniz yeterli.
• Claude Sonnet 4.6 gibi başka değerleri kabul eden modeller: Daha tutarlı çıktı için temperature'ı düşüren bir istek bu etkiyi kaybeder. Rehber açıkça "yerine geçen başka bir ayar yok" diyor.

Rehberin sunduğu iki seçenek var: parametreyi göndermeyi bırakmak ya da varsayılan dışı bir değere gerçekten ihtiyaç duyan isteği 2023-06-01'de tutmak. Örneğin sınıflandırma veya veri çıkarma işlerinde eski bir modelle temperature: 0 kullanıyorsanız, geçiş öncesinde bu iş akışının çıktı tutarlılığını test etmeniz şart. Güncel modellerde tutarlılık için örnekleme parametreleri yerine net talimatlara, örnek çıktılara ve yapılandırılmış çıktıya yaslanmak daha sağlıklı bir yaklaşım.

# Önce (2023-06-01 ile çalışıyordu)
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    temperature=0,
    messages=[{"role": "user", "content": "Bu yorumu olumlu/olumsuz diye sınıflandır."}],
)

# Sonra (2026-10-21): temperature yok, varsayılanlarla örneklenir
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Bu yorumu olumlu/olumsuz diye sınıflandır."}],
)

Asistan Mesajında document Bloğu Artık Hata Veriyor

Eğer document bloklarını doğrudan assistant rolündeki mesajlara koyuyorsanız, 2026-10-21'de bu istek 400 hatası döner. Belgeleri user mesajlarında gönderin. Önemli bir istisna var: başka bir bloğun içine yerleşmiş bir belge, örneğin Claude'un döndürdüğü bir web fetch aracı sonucunun içindeki belge, hâlâ kabul ediliyor. Yani Claude'un kendi cevaplarını konuşma geçmişine aynen geri koyan normal bir sohbet döngüsü etkilenmez; etkilenen, belgeyi elle asistan mesajına yerleştiren özel kurgular.

Kullanıcı Mesajındaki citations Dizisi Hata Veriyor

user mesajında, doğrudan ya da bir search_result bloğunun içinde, boş olmayan bir citations dizisi taşıyan text bloğu gönderirseniz 400 alırsınız. Çözüm, bu bloklardaki citations'ı kaldırmak. Şunlar ise hâlâ kabul ediliyor:

• Claude'un önceki cevapları gibi assistant mesajlarındaki text bloklarında bulunan alıntılar
• Belgeler ve arama sonuçları üzerindeki "citations": {"enabled": true} ayarı

Bu değişiklik, alıntıları içeren bir cevabı yanlışlıkla kullanıcı rolüyle geri gönderen RAG uygulamalarında ortaya çıkabilir. Konuşma geçmişini kendiniz kuruyorsanız, rolleri doğru atadığınızı kontrol edin.

Admin API ve Enterprise Analytics API'de Yeniden Adlandırılan Alanlar

Organizasyon yönetimini otomatikleştiriyorsanız (API anahtarı envanteri, RBAC, rate limit raporları gibi) bu bölüm sizi doğrudan ilgilendiriyor. 2026-10-21'de bu API'lerin yanıtları, yeniden adlandırılmış alanların eski adlarını artık içermiyor.

API / Uç nokta	Eski ad	Yeni ad
Admin: RBAC grupları (create, list, retrieve, update)	roles	role_ids
Admin: RBAC grup üyeleri (list, add ve üye çıkarma yanıtı)	group_id	rbac_group_id
Admin: RBAC rolleri (list, retrieve)	name	display_name
Admin: Organizasyon ve workspace rate limitleri	group_type	group.type
Admin: API anahtarları (list, retrieve, update)	workspace_id	scope (farklı değerler)
Analytics: Kullanıcı bazlı usage ve cost raporları	actor.email	actor.email_address
Analytics: Activity summaries	summaries	data

Rate limit liste uç noktalarındaki group_type sorgu parametresi ve API anahtarı listesindeki workspace_id filtresi değişmedi; değişen yalnızca yanıttaki alanlar.

API Anahtarlarında workspace_id → scope Geçişi

Bu, basit bir yeniden adlandırmadan fazlası. 2023-06-01'de bir API anahtarının workspace_id değeri bağlı olduğu workspace'in kimliğiydi; ancak Default Workspace'e bağlı anahtarlarda ve tek bir workspace'e bağlı olmayan "tüm workspace'ler" anahtarlarında null dönüyordu. Yani null iki farklı anlama geliyordu.

2026-10-21'de workspace_id tamamen kalktı. Yerine scope okunuyor:

• Bir workspace'e bağlı anahtarda (Default Workspace dahil) scope.workspace_id o workspace'in gerçek kimliğidir.
• Tüm workspace'lere erişen bir anahtarın scope değeri {"type": "organization"} olur ve içinde workspace_id bulunmaz.

Kodunuz null değerini "Default Workspace" olarak yorumluyorsa, artık scope.workspace_id'yi Default Workspace'in kimliğiyle karşılaştırmanız gerekiyor. Bu kimliği bulmak için List Workspaces uç noktasını include_default=true ile çağırıp adı "Default" olan workspace'i alın.

SDK Tarafındaki Değişiklikler

Yeni SDK sürümlerinin bir kısmı API sürümünden bağımsız kırılma değişiklikleri içeriyor. API sürümündeki değişiklikler de SDK'lara yansıdı: kaldırılan parametreler ve eski alan adları SDK tiplerinden, CLI bayraklarından ve CLI çıktısından da çıkarıldı.

MessageParam Artık Rol Başına Ayrı Tiplerin Birleşimi

Önceki sürümlerde MessageParam tüm roller için tek bir tipti. Artık her rolün kendi tipi var: UserMessageParam, AssistantMessageParam ve SystemMessageParam. BetaMessageParam da aynı şekilde BetaUserMessageParam, BetaAssistantMessageParam ve BetaSystemMessageParam olarak bölündü. SDK'nın gönderdiği isteklerin alanları ve değerleri aynı kaldı; değişen, tipler.

Python'da {"role": "user", "content": "Hello"} gibi sözlük olarak yazılan mesajlar hiçbir değişiklik gerektirmiyor. MessageParam adı tip açıklamalarında (list[MessageParam] gibi) çalışmaya devam ediyor. Ancak bu adı fonksiyon gibi çağırmak veya ondan alt sınıf türetmek artık TypeError fırlatıyor:

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

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

Tip denetleyicisi kullanıyorsanız bir ince nokta daha var: role değeri birden fazla rolü tutabilen bir değişkense, oluşturduğunuz sözlük birleşimdeki hiçbir tiple eşleşmez. Çözüm, sözlüğü her rol için ayrı kurmak:

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


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

TypeScript'te yalnızca tipler değişti. Rolünü belirten bir mesaj literali, örneğin { role: "user", content: "Hello, Claude" }, eskisi gibi tip denetiminden geçiyor; bu yüzden çoğu kod değişiklik gerektirmiyor. Sorun çıkarabilecek iki kalıp var. Birincisi, her rolden mesajı işleyen kodun içerik bloklarını değiştirmeden önce role'ü kontrol etmesi gerekiyor:

// Önce
const copy: Anthropic.MessageParam = { ...message, content: blocks };

// Sonra
const copy: Anthropic.MessageParam =
  message.role === "system" ? message : { ...message, content: blocks };

İkincisi, bir interface bir union'ı genişletemez. interface StoredMessage extends Anthropic.MessageParam gibi bir tanımınız varsa bunu bir tip takma adına çevirin:

// Önce
interface StoredMessage extends Anthropic.MessageParam {
  id: string;
}

// Sonra
type StoredMessage = Anthropic.MessageParam & { id: string };

Diğer dillerde değişiklik daha görünür. Go'da MessageParam artık OfUser, OfAssistant ve OfSystem alanlarından birini dolduran bir union; struct literalleri rol tipini adlandırıyor ve Role alanı yazılmıyor. Rehbere göre NewUserMessage, NewAssistantMessage gibi yardımcılarla mesaj kuran Go kodu değişmeden çalışıyor. Java'da MessageParam.builder() kaldırıldı; yerine MessageParam.ofUser("Hello, Claude") gibi rol fabrika metotları geldi. C#'ta new UserMessageParam { Content = "Hello, Claude" } yazılıyor ve Role enum'ları kaldırıldı.

API Anahtarı Artık Authorization: Bearer ile Gidiyor

Bu, kurumsal ortamlarda en çok sürpriz yaratacak değişiklik. Yeni SDK'lar ve CLI, API anahtarınızı X-Api-Key başlığı yerine Authorization: Bearer <key> olarak gönderiyor:

# Önce
X-Api-Key: <key>

# Sonra
Authorization: Bearer <key>

Claude API anahtarı her iki başlıkta da kabul ediyor; yani doğrudan api.anthropic.com'a giden istekler sorunsuz çalışır. Sorun, arada bir katman olduğunda çıkar. Rehber şu durumlar için değişiklik yapmanızı istiyor:

• X-Api-Key başlığını okuyan veya ayarlayan bir proxy ya da gateway
• Kendi programınızda bu başlığı okuyan middleware, log filtresi veya test stub'ı

Log maskeleme kurallarınızı özellikle kontrol edin: yalnızca X-Api-Key'i maskeleyen bir log filtresi, artık Authorization başlığında giden anahtarı maskelemeyebilir.

Bazı istemciler istisna: Python'daki AnthropicFoundry, TypeScript'teki @anthropic-ai/foundry-sdk ve diğer dillerdeki Foundry istemcileri anahtarı hâlâ x-api-key olarak gönderiyor. Bedrock Mantle istemcileri zaten bearer token kullanıyordu.

Proxy'nizi hemen değiştiremiyorsanız anahtarı eski başlığa geri taşıyabilirsiniz. TypeScript'te rehberin önerdiği yol:

const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }
});

Python'da ise HTTP istemcisine her istekte (yeniden denemeler dahil) çalışan bir auth fonksiyonu veriliyor:

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))

ant CLI'da böyle bir kaçış yolu yok: CLI'ın kendi başlığınızı eklemeye yarayan bir bayrağı veya ortam değişkeni bulunmadığından X-Api-Key gönderemiyor. --base-url veya ANTHROPIC_BASE_URL ile bir proxy'ye yönlendiriyorsanız proxy'yi Authorization okuyacak şekilde güncellemeniz gerekiyor.

İstek bazında başlık oynayan kod da etkileniyor. Örneğin Python'da extra_headers={"X-Api-Key": other_key} artık istemcinin anahtarının yerini almıyor; iki anahtar birden gidiyor. Tek bir istekte başka bir anahtar kullanmak için extra_headers={"Authorization": f"Bearer {other_key}"} yazmanız gerekiyor. Anahtarı bir istekten çıkarmak için de artık X-Api-Key değil Authorization başlığını omit etmelisiniz.

Bir İstemci Artık Tek Kimlik Bilgisi Tutuyor

API anahtarı ve kimlik doğrulama token'ı aynı başlığı paylaştığı için bir SDK istemcisi artık yalnızca bir kimlik bilgisi tutuyor. Python'da bunun pratik anlamı:

• api_key, auth_token, credentials, config ve profile arasından en fazla birini verin. Kurucuya ikisini birden vermek ValueError fırlatır (None sayılmaz).
• Verdiğiniz kimlik bilgisi tek kaynaktır; istemci ortam değişkenlerine veya diske ayrıca bakmaz.
• Hiçbirini vermezseniz şu sırayla ilk dolu olan kullanılır: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_PROFILE'ın adlandırdığı profil, workload identity federation değişkenleri, diskteki aktif profil. İlk ikisi birlikte tanımlıysa istemci bir kez uyarı loglar.
• copy() ve with_options() ile verdiğiniz kimlik bilgisi istemcinin mevcut kimlik bilgisinin yerini alır.

client = Anthropic(api_key=key, auth_token=token)
# Önce: X-Api-Key: <key> ve Authorization: Bearer <token> gönderiyordu
# Sonra: ValueError fırlatır

Eskiden bir gateway için token ve arkasındaki API için anahtar gönderen kurgular vardı. TypeScript ve C# için rehberin önerisi, X-Api-Key'i varsayılan başlıklarla elle ayarlayıp token'ı korumak ve gateway'in isteği iletmeden önce kendi Authorization başlığını kaldırmasını sağlamak. Rehberin ifadesiyle Claude API her istek için tek bir kimlik bilgisi bekliyor.

Kaldırılan Diğer Özellikler

• Text Completions: Eski Text Completions API'si TypeScript, Go, Java ve Ruby SDK'larından ve CLI'dan kaldırıldı. Yeni modeller ve özellikler bunu desteklemiyor; Messages API'ye geçin.
• Models metotlarında betas: Beta olmayan Models metotları artık betas almıyor. Python'da client.models.list(betas=[beta]) yerine client.beta.models.list(betas=[beta]); CLI'da ant models list --beta "$BETA" yerine ant beta:models list --beta "$BETA" kullanılıyor.
• Tool runner'da istemci taraflı compaction: TypeScript'teki compactionControl seçeneği ve Ruby'deki compaction_control: kaldırıldı. Yerine, konuşmayı ek bir istemci isteği yerine API içinde özetleyen sunucu taraflı compaction geliyor. Tetikleme eşiği en az 50.000 token olmalı.
• Go: Go 1.25 veya sonrası gerekiyor; vertex.DefaultVersion ve bedrock.DefaultVersion kaldırıldı.
• Ruby: Anthropic::VertexClient::DEFAULT_VERSION ve Anthropic::BedrockClient::DEFAULT_VERSION kaldırıldı.

TypeScript'te otomatik compaction'ı korumak için rehberdeki dönüşüm şöyle:

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

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

ant CLI: --api-key ve --auth-token Bayrakları Kaldırıldı

ant 2.0.0 artık API anahtarını veya token'ı bayrak değeri olarak almıyor; çünkü komut satırındaki bir değer kabuk geçmişinde ve süreç listelerinde görünür. Bu iki bayrak v1.27.0'dan beri kullanımdan kaldırılma uyarısı veriyordu. Hâlâ bunlardan birini geçen bir komut flag provided but not defined hatasıyla duruyor.

Kaldırılan	Yerine
--api-key <key>	ANTHROPIC_API_KEY, --api-key-stdin veya ant auth login
--auth-token <token>	ANTHROPIC_AUTH_TOKEN veya --auth-token-stdin

# Önce
ant --api-key "$KEY" models list

# Sonra, ortam değişkeninden
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Sonra, bir parola yöneticisinden
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

--api-key-stdin ve --auth-token-stdin standart girdinin tamamını okuduğu için, bunları kullanan bir komut istek gövdesini stdin'den değil bayraklardan almak zorunda. CI betiklerinizde stdin ile JSON gövde besliyorsanız bunu göz önünde bulundurun.

Lisans: MIT'ten Apache 2.0'a

Yeni sürümlerden itibaren SDK'lar ve CLI Apache License 2.0 ile lisanslanıyor; önceki sürümler MIT lisansında kalıyor. Kod değişikliği gerekmiyor, ancak şirketinizde bağımlılık lisanslarını takip eden bir süreç (SBOM, lisans tarayıcı vb.) varsa kayıtları güncellemeniz gerekiyor.

Claude Code ile Geçiş: /claude-api api-version

Claude Code kullanıyorsanız geçişi elle yapmak zorunda değilsiniz. 2.1.307 sürüm notlarına göre Claude Code'a, Claude API kodunu 2026-10-21 API sürümüne taşımak için /claude-api api-version komutu eklendi. /claude-api, Claude API ve SDK kullanımına dair referans bilgi taşıyan bir skill; api-version alt komutu onu doğrudan bu geçiş görevine yönlendiriyor. Skill'lerin nasıl çalıştığını merak ediyorsanız Claude Code Agent Skills rehberine göz atabilirsiniz.

Komutu proje kökünde, temiz bir Git çalışma ağacında çalıştırmanızı öneririm; böylece yapılan değişiklikleri git diff ile tek tek inceleyebilirsiniz:

git switch -c claude-api-2026-10-21
claude
> /claude-api api-version

Ajanın yaptığı değişiklikleri yine de aşağıdaki kontrol listesiyle doğrulayın. Özellikle temperature kaldırıldığında çıktı davranışı değişebilecek iş akışlarını ve proxy/gateway katmanını bir yapay zekâ ajanı kod tabanınızdan göremeyebilir; bunlar sizin altyapı bilginizi gerektiriyor.

Adım Adım Geçiş Akışı: Gerçek Bir Proje Örneği

Resmi rehberin önerdiği sıra üç adımdan oluşuyor: (1) 2026-10-21'e geçin, (2) kırılma değişiklikleri için kodu güncelleyin, (3) yayına almadan önce test edin. Rehber ayrıca SDK yükseltmesini kod düzeltmeleriyle birlikte yayına almanızı istiyor. Bunu, Claude API'yi kullanan tipik bir Python servisine (destek taleplerini sınıflandıran ve özetleyen bir FastAPI uygulaması düşünün) uygulayalım.

1. Envanter çıkarın

Önce kod tabanında etkilenen kalıpları arayın. Aşağıdaki komutlar, bu yazıdaki kırılma değişikliklerine karşılık gelen anahtar kelimeleri tarar:

# Kaldırılan örnekleme parametreleri
grep -rnE "temperature|top_p|top_k" --include="*.py" .

# Eski API sürümünü elle ayarlayan yerler
grep -rn "2023-06-01" .

# X-Api-Key'e bağımlı middleware, proxy, log filtresi, test
grep -rni "x-api-key" .

# Tek-kimlik-bilgisi kuralını bozabilecek kurulumlar
grep -rnE "auth_token|ANTHROPIC_AUTH_TOKEN" .

# Models metotlarına betas geçen çağrılar
grep -rn "models.list(betas\|models.retrieve(" --include="*.py" .

Admin API kullanıyorsanız workspace_id, roles, group_type, actor.email ve summaries alanlarını okuyan kodu da bu listeye ekleyin.

2. Riskli iş akışlarını belirleyin

Envanterden çıkan her temperature kullanımı için şu soruyu sorun: bu çağrı hangi modele gidiyor? Claude 4.7 veya sonrasıysa parametreyi silmek davranışı değiştirmez. Claude Sonnet 4.6 gibi düşük temperature değerini gerçekten uygulayan bir modelse, o iş akışının çıktı tutarlılığı değişebilir. Bu durumda ya modeli güncellemeyi planlayın ya da o isteği geçici olarak 2023-06-01'de tutun.

3. SDK'yı yükseltin ve kodu düzeltin

pip install --upgrade "anthropic>=2.0.0"
pip freeze | grep -i anthropic

Ardından envanterdeki her maddeyi düzeltin: örnekleme parametrelerini silin, MessageParam(...) çağrılarını sözlüğe çevirin, client.models.list(betas=...) çağrılarını client.beta.models'a taşıyın, hem api_key hem auth_token veren kurucu çağrılarını teke indirin.

4. Tip denetimi ve testler

MessageParam değişikliklerinin büyük kısmı yalnızca tip denetiminde ortaya çıkıyor. Projenizde mypy veya pyright varsa yükseltmeden sonra mutlaka çalıştırın. Ardından gerçek API'ye karşı entegrasyon testlerinizi koşun; 400 hataları burada yakalanır. Bir proxy kullanıyorsanız testleri proxy üzerinden de çalıştırın ki Authorization başlığı değişikliğinin etkisini görün.

5. Kademeli yayın

Rehberin önerdiği gibi SDK yükseltmesini ve kod düzeltmelerini aynı sürümde yayına alın. Önce düşük trafikli bir ortamda (staging) çalıştırıp 400 hatalarını ve log maskelemeyi izleyin, sonra üretime taşıyın.

Sorun Giderme: Sık Görülecek Hatalar

• 400 hatası, örnekleme parametresi nedeniyle: İstekte temperature, top_p veya top_k kalmış. Varsayılan değerle (ör. temperature: 1) gönderseniz bile hata alırsınız; parametreyi tamamen silin. Bu parametreyi bir üst katmanda (kendi wrapper'ınız, bir framework ayarı) ekleyen kod olup olmadığını da kontrol edin.
• 400 hatası, belge veya alıntı nedeniyle: Konuşma geçmişinde asistan mesajına doğrudan document bloğu veya kullanıcı mesajına dolu citations dizisi girmiş. Rolleri ve blok yerleşimini kontrol edin.
• Proxy 401/403 dönüyor: Proxy anahtarı X-Api-Key'den okuyor ama SDK artık Authorization: Bearer gönderiyor. Proxy'yi güncelleyin veya yukarıdaki örneklerle anahtarı X-Api-Key'e geri taşıyın.
• Python'da ValueError: İstemciye birden fazla kimlik bilgisi verilmiş (ör. api_key ve auth_token). Birini kaldırın.
• Python'da TypeError: MessageParam(...) fonksiyon gibi çağrılıyor veya ondan alt sınıf türetiliyor. Sözlük kullanın ya da rol tipinden (UserMessageParam) türetin.
• ant: flag provided but not defined: Betik hâlâ --api-key veya --auth-token kullanıyor. Ortam değişkenine veya --api-key-stdin'e geçin.
• Go'da "yükselttim ama hâlâ eski sürüm": Importlar /v2 ile başlamıyor ya da CLI eski go install yolundan kuruldu. Eski yol uyarı vermeden v1 kurmaya devam ediyor.
• node_modules'te iki farklı @anthropic-ai/sdk: Platform paketlerinden biri (ör. @anthropic-ai/bedrock-sdk) v1'e taşınmamış. Hepsini aynı anda yükseltin.
• PHP'de sürüm değişmiyor: composer update kısıt içinde kalır; composer require "anthropic-ai/sdk" çalıştırın.
• Bedrock'ta eski model hata veriyor: 2026-10-21 Bedrock'ta yalnızca Claude 4.7 ve sonrası için geçerli. Eski modeli kullanan çağrıları eski SDK/sürümde tutun veya modeli güncelleyin.

Kimler Hemen Geçmeli, Kimler Bekleyebilir?

Resmi sürüm sayfası mümkün olduğunda en son API sürümünün kullanılmasını öneriyor. Öte yandan geçiş rehberi, varsayılan dışı örnekleme değerine ihtiyaç duyan istekleri veya Bedrock'taki eski model çağrılarını 2023-06-01'de tutmayı açıkça bir seçenek olarak sunuyor. Benim pratik önerim şöyle:

Durum	Öneri
Yeni proje, doğrudan Claude API, güncel modeller	Doğrudan yeni SDK major sürümüyle başlayın
Mevcut proje, Claude 4.7+ modeller, proxy yok	Kısa bir envanter ve test turuyla geçin; risk düşük
Kurumsal gateway/proxy arkasında	Önce gateway'in Authorization okumasını sağlayın, sonra SDK'yı yükseltin
Eski modelde düşük temperature'a bağımlı iş akışı	Model geçişini planlayın; o zamana kadar ilgili istekleri 2023-06-01'de tutun
Bedrock'ta Opus 4.6 veya öncesi	Mevcut SDK sürümünü sabitleyin; model geçişiyle birlikte yükseltin
Admin API ile anahtar/RBAC otomasyonu	Alan adlarını ve scope mantığını güncelleyip yükseltin

Bekleme kararı verdiyseniz, paket yöneticinizde SDK'yı mevcut major sürüme sabitleyin (ör. Python'da anthropic<2, npm'de @anthropic-ai/sdk@^0). Aksi hâlde otomatik bağımlılık güncelleme araçları SDK'yı yeni major sürüme taşıyıp API sürümünü sizin haberiniz olmadan değiştirebilir.

Model tarafındaki değişiklikleri ayrıca takip etmek isterseniz Claude Sonnet 5.5 rehberinde modelin kırılma değişikliklerini ve effort kalibrasyonunu ayrıntılı anlattım.

Sıkça Sorulan Sorular

2023-06-01 sürümü çalışmaya devam ediyor mu?

Geçiş rehberi, varsayılan dışı örnekleme değerlerine ihtiyaç duyan istekleri ve Bedrock'taki eski model çağrılarını 2023-06-01'de tutmayı bir seçenek olarak sunuyor; yani eski sürüm şu an kullanılabilir durumda. Resmi sürüm sayfası ise mümkün olduğunda en son sürümün kullanılmasını öneriyor. Yeni projelerde doğrudan 2026-10-21 ile başlamak en mantıklısı.

temperature parametresi kaldırıldıysa çıktı tutarlılığını nasıl sağlarım?

Rehbere göre kaldırılan temperature, top_p ve top_k'nın yerini alan başka bir ayar yok; istekler varsayılanlarla (temperature 1.0) örnekleniyor. Claude 4.7 ve sonraki modeller zaten yalnızca varsayılanları kabul ettiği için bu modellerde davranış değişmiyor. Daha eski bir modelde düşük temperature'a güveniyorsanız ya parametreyi bırakıp sonucu test edin ya da o isteği 2023-06-01'de tutun.

SDK güncellemesi API anahtarımın gönderilme şeklini değiştirir mi?

Evet. Yeni SDK'lar ve ant CLI anahtarı X-Api-Key yerine Authorization: Bearer başlığıyla gönderiyor. Claude API iki başlığı da kabul ettiği için doğrudan bağlantılar etkilenmez; ancak X-Api-Key okuyan proxy, gateway, middleware veya log filtrelerinin güncellenmesi gerekir. Foundry istemcileri ise anahtarı hâlâ x-api-key ile gönderiyor.

Amazon Bedrock'ta 2026-10-21 kullanabilir miyim?

Yalnızca Claude 4.7 ve sonraki modellerle. Bedrock'ta Opus 4.6 veya daha eski bir modeli çağırıyorsanız mevcut SDK sürümünüzde kalın ya da bugün gönderdiğiniz API sürümünü göndermeye devam edin. Bu çağrıları yeni sürüme taşımak için önce Claude 4.7 veya sonrası bir modele geçmeniz gerekiyor.

Claude Code bu geçişte nasıl yardımcı olur?

Claude Code 2.1.307 ile gelen /claude-api api-version komutu, projenizdeki Claude API kodunu 2026-10-21 sürümüne taşımak için tasarlandı. Komutu ayrı bir Git dalında çalıştırıp değişiklikleri git diff ile incelemeniz, ardından tip denetimi ve entegrasyon testleriyle doğrulamanız önerilir.

Özet

2026-10-21, Claude API'nin üç yılı aşkın süredir ilk kırılma değişikliği içeren sürümü. API tarafında temperature, top_p ve top_k kaldırıldı; asistan mesajındaki doğrudan document blokları ve kullanıcı mesajındaki dolu citations dizileri artık 400 döndürüyor; Admin ve Analytics API'lerinde eski alan adları yanıtlardan çıktı. SDK tarafında Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 ve ant 2.0.0 yeni sürümü varsayılan olarak gönderiyor. Bu sürümler MessageParam'ı rol bazlı bir birleşime çeviriyor, anahtarı Authorization: Bearer ile gönderiyor, istemci başına tek kimlik bilgisine izin veriyor ve lisansı Apache 2.0'a taşıyor.

Geçiş için izlenecek yol basit: envanter çıkarın, riskli temperature kullanımlarını ve proxy katmanını belirleyin, SDK'yı yükseltip kodu düzeltin, tip denetimi ve entegrasyon testleriyle doğrulayın, ardından yükseltmeyi düzeltmelerle aynı sürümde yayına alın. Claude Code kullanıyorsanız /claude-api api-version bu işin büyük kısmını sizin yerinize başlatabilir.

Devam okumaları için: Claude Code'un skill sistemini Agent Skills rehberinde, Claude Sonnet 5.5'in getirdiklerini Claude Sonnet 5.5 rehberinde, token ve maliyet yönetimini de maliyet ve context yönetimi rehberinde bulabilirsiniz.