Переход на версию API 2026-10-21

В этом руководстве перечислены изменения кода, необходимые для перехода с версии API 2023-06-01 на 2026-10-21. В шагах обновления по порядку описано, что нужно сделать.

Шаги обновления

1. 1

   Переход на 2026-10-21

   Если вы используете SDK, ваши запросы используют версию API, которая была актуальной на момент выпуска мажорной версии вашего SDK. Версии, указанные для вашего языка, — первые, которые используют 2026-10-21, поэтому обновитесь до них. Если вы вызываете API без SDK, установите заголовок anthropic-version в значение 2026-10-21.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   Обновите пакет anthropic до версии 2.0.0.

   Выпустите обновление вместе с исправлениями из следующего шага.

2. 2

   Обновите код с учётом критических изменений

   Просмотрите критические изменения и обновите код для каждого из них, которое вас затрагивает. Также внесите изменения кода, которые требуются новой версии SDK или CLI.

3. 3

   Протестируйте с 2026-10-21

   Протестируйте свою интеграцию с 2026-10-21 перед выпуском.

Критические изменения

Messages API

Эти изменения применяются к запросам к Messages API (POST /v1/messages), к подсчёту токенов и к каждому запросу в Message Batch, созданном с 2026-10-21.

Блоки документов в сообщениях ассистента возвращают ошибку

Затрагивает вас, если вы отправляете блоки document непосредственно в сообщениях assistant.

В 2026-10-21 запрос, который помещает блок document непосредственно в сообщение assistant, возвращает ошибку 400. Вместо этого отправляйте документы в сообщениях user. Документ, вложенный в другой блок, например в результат инструмента веб-загрузки, который вернул Claude, по-прежнему принимается.

Цитаты в сообщениях пользователя возвращают ошибку

Затрагивает вас, если вы отправляете citations в блоках text в сообщениях user, в том числе внутри блоков search_result.

В 2026-10-21 запрос, который отправляет блок text с непустым массивом citations в сообщении user, возвращает ошибку 400. Удалите citations из этих блоков. Цитаты в блоках text в сообщениях assistant, например в предыдущих ответах Claude, которые вы отправляете обратно, по-прежнему принимаются, как и настройка "citations": {"enabled": true} для документов и результатов поиска.

Параметры сэмплирования удалены

Затрагивает вас, если вы отправляете temperature, top_p или top_k в запросах Messages или запросах Message Batch.

В 2026-10-21 запрос, который отправляет temperature, top_p или top_k, возвращает ошибку 400, даже при значении параметра по умолчанию.

Удалите эти три параметра из своих запросов.

Начиная с последних мажорных версий, в SDK и CLI этих трёх параметров больше нет.

Без этих параметров запрос выполняет сэмплирование с их значениями по умолчанию, включая temperature, равную 1.0, — так же, как запрос 2023-06-01, в котором они не указаны. Модели, которые уже принимают только значения по умолчанию, такие как Claude 4.7 и более поздние модели, выполняют сэмплирование как прежде. На моделях, которые принимают другие значения, таких как Claude Sonnet 4.6, запрос, в котором temperature понижалась для более согласованного вывода, теряет этот эффект. Никакая другая настройка его не заменяет. Если запрос зависит от значения, отличного от значения по умолчанию, либо перестаньте отправлять этот параметр, либо оставьте этот запрос на 2023-06-01.

Admin API и Claude Enterprise Analytics API

Затрагивает вас, если ваш код читает поля ответов Admin API или Claude Enterprise Analytics API, указанные в следующих таблицах.

В 2026-10-21 ответы Admin API и Claude Enterprise Analytics API больше не содержат старых имён переименованных полей. Используйте вместо них новые имена.

Admin API:

Claude Enterprise Analytics API:

Параметр запроса group_type в эндпоинтах получения списка ограничений скорости и фильтр workspace_id в эндпоинте получения списка ключей API не изменились.

workspace_id в ключах API

Затрагивает вас, если ваш код читает workspace_id в ключах API.

В 2023-06-01 поле workspace_id ключа API — это ID рабочего пространства, к которому привязан ключ, или null для ключа, привязанного к Default Workspace, и для ключа, который не привязан к одному рабочему пространству (ключ для всех рабочих пространств).

В 2026-10-21 поле workspace_id удалено. Вместо него читайте scope: для ключа, привязанного к рабочему пространству, включая Default Workspace, scope.workspace_id — это реальный ID этого рабочего пространства, а ключ для всех рабочих пространств имеет scope, равный {"type": "organization"}, без workspace_id.

Если ваш код рассматривал workspace_id, равный null, как Default Workspace, вместо этого сравнивайте scope.workspace_id с ID вашего Default Workspace. Чтобы найти этот ID, вызовите List Workspaces с include_default=true и возьмите рабочее пространство с именем "Default".

Изменения SDK и CLI

Более ранние версии SDK и CLI отправляли anthropic-version: 2023-06-01 с каждым запросом. Версии, указанные в разделе Переход на 2026-10-21, отправляют 2026-10-21. Изменения из раздела Критические изменения применяются и к ним: удалённые параметры и старые имена полей также исчезли из типов SDK, а также из флагов и вывода CLI.

Версия API в Amazon Bedrock и Google Cloud

Клиент SDK для Google Cloud's Agent Platform указывает версию в теле запроса, а не в заголовке. Он отправляет anthropic_version: 2026-10-21, тогда как более ранние версии отправляли vertex-2023-10-16, и не отправляет заголовок anthropic-version.

Клиент Amazon Bedrock делает то же самое. Он отправляет anthropic_version: 2026-10-21, тогда как более ранние версии отправляли bedrock-2023-05-31, и не отправляет заголовок anthropic-version. Модели старше Claude Opus 4.7 пока не поддерживают версию API 2026-10-21 в Bedrock, и запрос, в котором она указана, может получить ошибку 400. Если вы используете одну из них, пока оставайтесь на более ранней версии SDK или обновитесь и отправляйте bedrock-2023-05-31 самостоятельно.

MessageParam — это объединение с отдельным типом для каждой роли

В более ранних версиях MessageParam был одним типом для всех ролей. Теперь у каждой роли есть собственный тип: UserMessageParam, AssistantMessageParam и SystemMessageParam. BetaMessageParam разделён таким же образом — на BetaUserMessageParam, BetaAssistantMessageParam и BetaSystemMessageParam. Запросы, которые отправляет SDK, содержат те же поля и значения, что и раньше.

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

# После
message: MessageParam = {"role": "user", "content": "Hello"}

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


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

Перечисления с одним значением стали константами

Это изменение затрагивает SDK для C#, Go, Java, PHP и Ruby, а также один флаг CLI. В более ранних версиях обязательное поле, которое может содержать только одно значение, имело собственный тип «enum» (перечисление) с единственным членом. Теперь такие поля являются константами, а типы перечислений удалены. JSON, который SDK отправляет и читает, остаётся прежним.

Клиентское сжатие удалено из tool runner

Это изменение затрагивает SDK для TypeScript и Ruby. «Compaction» (сжатие) на стороне клиента в «tool runner» (средство запуска инструментов) удалено в пользу сжатия на стороне сервера, которое суммирует разговор внутри API, а не с помощью дополнительного запроса от клиента.

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

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

Порог срабатывания должен составлять не менее 50 000 токенов. Другие параметры (pause_after_compaction, пользовательские instructions) описаны в разделе сжатие.

Text Completions удалён

Устаревший Text Completions API удалён из SDK для TypeScript, Go, Java и Ruby, а также из CLI. Новые модели и функции его не поддерживают. Вместо него используйте Messages API.

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

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

betas удалён из не-бета методов Models

Не-бета методы Models больше не принимают betas, а команды ant models больше не принимают --beta. Чтобы отправлять бета-заголовки, вызывайте те же методы у client.beta.models или используйте ant beta:models в CLI. В SDK эти методы возвращают BetaModelInfo, тогда как не-бета методы возвращают ModelInfo.

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

# После
page = client.beta.models.list(betas=[beta])

Ключи API отправляются как Authorization: Bearer

SDK и CLI отправляют ваш ключ API как Authorization: Bearer <key> вместо заголовка X-Api-Key, поэтому измените любой «proxy» (прокси) или шлюз, который читает или устанавливает X-Api-Key, чтобы он использовал Authorization, или отправляйте ключ в X-Api-Key самостоятельно. Claude API принимает ключ в любом из этих заголовков, поэтому программе, которая обращается к API напрямую, ничего менять не нужно.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Если прокси или шлюз читает 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))

Если вы устанавливали или удаляли X-Api-Key в запросе

Это изменение затрагивает SDK для Python, TypeScript, Go, PHP и Ruby.

Если вы удаляли X-Api-Key, чтобы запрос отправлял только токен аутентификации, удалите этот код, а не изменяйте его, потому что удаление Authorization удалит и токен. Клиент хранит одни учётные данные, поэтому убедитесь, что это именно токен: если в коде ничего не передано, а заданы и ANTHROPIC_API_KEY, и ANTHROPIC_AUTH_TOKEN, клиент использует ключ.

Клиент хранит одни учётные данные

Ключ API и токен аутентификации теперь используют один заголовок, поэтому клиент SDK хранит одни учётные данные. Если в коде ничего не передано, клиент следует порядку приоритета учётных данных.

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

# До: отправлялись `X-Api-Key: <key>` и `Authorization: Bearer <token>`
# После: выбрасывается `ValueError`

Изменения в одном SDK или CLI

Каждое из этих изменений затрагивает один SDK или CLI.

# До
ant --api-key "$KEY" models list

# После: из переменных окружения
export ANTHROPIC_API_KEY="$KEY"
ant models list

# После: из менеджера секретов
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

Лицензия — Apache 2.0

Начиная с этих версий, SDK и CLI распространяются по лицензии Apache License, Version 2.0. Более ранние версии остаются под лицензией MIT. Изменения кода не требуются. Если вы отслеживаете лицензии своих зависимостей, обновите соответствующие записи.

• TypeScript: пакеты платформ (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk и @anthropic-ai/google-cloud-sdk) меняют лицензию в собственных выпусках 1.0.0.
• C#: остальные пакеты (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud и Anthropic.Mcp) меняют лицензию в собственных выпусках 1.0.0.
• Java: изменение распространяется на все артефакты com.anthropic.