Nowa wersja Claude API 2026-10-21. Co się zmienia i jak przejść migrację

Czym jest wersja 2026-10-21 i kogo dotyczy

Claude API wersjonuje zachowanie interfejsu datą przesyłaną w nagłówku anthropic-version. Do tej pory praktycznie wszystkie integracje korzystały z wersji 2023-06-01. Wersja 2026-10-21 jest pierwszą od ponad trzech lat, która zmienia format zapytań i odpowiedzi w sposób wymagający poprawek w kodzie.

Zmiana dotyczy przede wszystkim firm i programistów, którzy wywołują Claude bezpośrednio przez API Anthropic albo przez SDK, także w wariantach dla Amazon Bedrock i Google Cloud. Użytkowników aplikacji Claude w przeglądarce i na telefonie migracja nie dotyczy. Dokumentacja Anthropic nie podaje terminu wyłączenia wersji 2023-06-01 i w kilku miejscach wskazuje ją jako opcję dla zapytań, które jeszcze nie mogą przejść na nową wersję.

Najważniejsze zmiany w Messages API

Zmiany obejmują zapytania do Messages API, liczenie tokenów i każde zapytanie w paczce Message Batches utworzonej w nowej wersji. Najwięcej integracji dotknie usunięcie parametrów próbkowania, czyli ustawień wpływających na losowość odpowiedzi modelu.

Bez tych parametrów model działa z wartościami domyślnymi, w tym z temperature równym 1,0. Dla Claude 4.7 i nowszych modeli nic się nie zmienia, bo i tak przyjmowały tylko wartości domyślne. Inaczej jest przy starszych modelach, takich jak Claude Sonnet 4.6. Jeśli aplikacja obniżała temperature, żeby uzyskać bardziej powtarzalne odpowiedzi, po migracji straci ten efekt, a Anthropic nie przewidział ustawienia zastępczego. Dla takich zapytań dokumentacja zaleca pozostanie przy wersji 2023-06-01.

• temperature, top_p i top_k - wysłanie dowolnego z nich zwraca błąd 400, nawet z wartością domyślną,
• bloki document umieszczone bezpośrednio w wiadomości assistant - błąd 400, dokumenty trzeba przesyłać w wiadomościach user,
• niepuste pole citations w blokach tekstowych wiadomości user, także w blokach search_result - błąd 400; cytowania w odpowiedziach Claude odsyłanych z powrotem nadal są akceptowane.

Zmienione nazwy pól w Admin API

Druga grupa zmian dotyczy narzędzi administracyjnych. Odpowiedzi Admin API i Claude Enterprise Analytics API nie zawierają już starych nazw pól. Skrypty, które raportują koszty, zarządzają kluczami lub grupami uprawnień, trzeba sprawdzić przed przełączeniem wersji.

Szczególnej uwagi wymaga pole workspace_id przy kluczach API. W starej wersji wartość null oznaczała zarówno klucz przypisany do domyślnego obszaru roboczego, jak i klucz obejmujący wszystkie obszary. W nowej wersji pole zastępuje scope: klucz z obszaru roboczego ma w nim rzeczywisty identyfikator, a klucz dla całej organizacji typ organization.

• grupy RBAC: roles zmienia się w role_ids,
• członkowie grup RBAC: group_id zmienia się w rbac_group_id,
• role RBAC: name zmienia się w display_name,
• limity zapytań organizacji i obszarów roboczych: group_type zmienia się w group.type,
• klucze API: workspace_id zastępuje scope o innej strukturze wartości,
• raporty użycia i kosztów w Enterprise Analytics API: actor.email zmienia się w actor.email_address, a summaries w data.

Co zmieniają nowe wersje SDK i ant CLI

Nowe SDK domyślnie wysyłają nagłówek z wersją 2026-10-21, więc samo podniesienie numeru biblioteki oznacza migrację API. Dodatkowo zawierają zmiany niezależne od wersji interfejsu. Usunięte parametry i stare nazwy pól zniknęły też z typów w kodzie, więc część błędów wyłapie kompilator lub analizator typów.

Zmiana nagłówka klucza dotyczy głównie firm, które kierują ruch do Claude przez własną bramkę, serwer proxy lub system rozliczania kosztów. Samo API przyjmuje klucz w obu nagłówkach, więc aplikacja łącząca się bezpośrednio z Anthropic nie wymaga poprawek w tym zakresie. W TypeScript trzeba jednocześnie podnieść do wersji 1 pakiety dla Bedrock, Vertex, Foundry, AWS i Google Cloud, bo inaczej menedżer pakietów zainstaluje drugą, starszą kopię SDK.

• klucz API trafia do nagłówka Authorization: Bearer zamiast X-Api-Key,
• typ MessageParam dzieli się na osobne typy dla ról user, assistant i system,
• starsze API Text Completions znika z SDK dla TypeScript, Go, Java i Ruby oraz z CLI,
• w TypeScript i Ruby z narzędzia tool runner usunięto kompaktowanie rozmowy po stronie klienta na rzecz kompaktowania po stronie serwera,
• ant CLI 2.0.0 nie przyjmuje już flag --api-key i --auth-token, a instalacja przez go install wymaga ścieżki z dopiskiem /v2.

Jak przejść migrację krok po kroku

Anthropic opisuje migrację w trzech etapach: przełączenie wersji, poprawki w kodzie i testy przed wdrożeniem. Na podstawie dokumentacji przygotowaliśmy listę czynności dla zespołu, który utrzymuje integrację produkcyjną.

1. Zablokuj w pliku zależności obecną główną wersję SDK, żeby automatyczna aktualizacja nie przełączyła aplikacji na nowe API bez testów.
2. Wyszukaj w kodzie temperature, top_p i top_k. Usuń je albo pozostaw dane zapytanie na wersji 2023-06-01, jeśli działa na starszym modelu i wymaga niższej losowości.
3. Sprawdź, czy aplikacja nie wysyła dokumentów w wiadomościach assistant ani cytowań w wiadomościach user.
4. Przejrzyj skrypty korzystające z Admin API i Enterprise Analytics API pod kątem zmienionych nazw pól, zwłaszcza workspace_id przy kluczach.
5. Jeśli ruch przechodzi przez bramkę lub proxy, dostosuj je do nagłówka Authorization albo ustaw w SDK wysyłanie klucza w X-Api-Key.
6. Podnieś SDK do nowej wersji głównej i uruchom testy na środowisku testowym, zanim zmiana trafi na produkcję.
7. Zaktualizuj rejestr licencji zależności, bo nowe SDK są objęte licencją Apache 2.0.

Ograniczenia i to, czego jeszcze nie wiadomo

Najważniejszą niewiadomą jest harmonogram wsparcia wersji 2023-06-01. Przewodnik migracji traktuje ją jako działającą alternatywę, ale nie podaje daty jej wyłączenia. Na razie migrację można więc zaplanować, zamiast wykonywać ją w pośpiechu. Ryzyko pojawia się tam, gdzie zależności aktualizują się automatycznie, na przykład przez boty aktualizujące biblioteki.

Zmiana licencji z MIT na Apache 2.0 nie wymaga poprawek w kodzie. Obie licencje pozwalają na użycie komercyjne, ale Apache 2.0 zawiera m.in. postanowienia o licencji patentowej i obowiązek zachowania informacji o zmianach w plikach. Działy prawne, które prowadzą rejestr licencji oprogramowania, powinny odnotować tę zmianę.

Co oznacza zmiana dla polskich firm

Polskie software house’y i zespoły produktowe, które wbudowały Claude w swoje usługi, powinny potraktować tę aktualizację jak każdą zmianę główną biblioteki. Dla większości prostych integracji, które nie ustawiają parametrów próbkowania, migracja ograniczy się do podniesienia SDK i testów. Więcej pracy czeka firmy z rozbudowanym raportowaniem kosztów przez Admin API oraz te, które korzystają z bramek pośredniczących.

W naszej ocenie warto przy okazji przejrzeć, z jakich modeli korzysta aplikacja. Jeśli integracja nadal używa starszego modelu tylko po to, by sterować temperaturą, migracja jest dobrym momentem na test nowszych modeli opisanych w naszych tekstach o Claude Sonnet 5.5 i Claude Haiku 5.5.