Claude Platform Docs
API 레퍼런스지원 및 구성

API 버전 2026-10-21로 마이그레이션

Claude API 통합을 API 버전 2023-06-01에서 2026-10-21로 업그레이드합니다: 설치할 SDK 버전과 수행해야 할 코드 변경 사항을 안내합니다.

이 가이드는 API 버전 2023-06-01에서 2026-10-21로 이전할 때 필요한 코드 변경 사항을 나열합니다. 업그레이드 단계에서 수행할 작업을 순서대로 설명합니다.

Claude Code

코드를 업그레이드하는 가장 쉬운 방법

/claude-api api-version

업그레이드 단계

  1. 2026-10-21로 전환

    SDK를 사용하는 경우, 요청은 해당 SDK의 메이저 버전이 릴리스되었을 때의 최신 API 버전을 사용합니다. 언어별로 표시된 버전이 2026-10-21을 처음으로 사용하는 버전이므로 해당 버전으로 업그레이드하세요. SDK 없이 API를 호출하는 경우 anthropic-version 헤더를 2026-10-21로 설정하세요.

    anthropic 패키지를 버전 2.0.0으로 업그레이드하세요.

    업그레이드는 다음 단계의 수정 사항과 함께 릴리스하세요.

  2. 호환성을 깨는 변경 사항에 맞게 코드 업데이트

    호환성을 깨는 변경 사항을 살펴보고, 영향을 받는 각 항목에 맞게 코드를 업데이트하세요. 또한 새 SDK 또는 CLI 버전에 필요한 코드 변경도 적용하세요.

  3. 2026-10-21에 대해 테스트

    릴리스하기 전에 2026-10-21에 대해 통합을 테스트하세요.

호환성을 깨는 변경 사항

Messages API

이 변경 사항은 Messages API(POST /v1/messages)에 대한 요청, 토큰 카운팅, 그리고 2026-10-21로 생성된 메시지 배치의 각 요청에 적용됩니다.

assistant 메시지의 문서 블록은 오류를 반환합니다

assistant 메시지에 document 블록을 직접 보내는 경우 영향을 받습니다.

2026-10-21에서는 assistant 메시지에 document 블록을 직접 배치한 요청이 400 오류를 반환합니다. 대신 user 메시지로 문서를 보내세요. Claude가 반환한 웹 페치 도구 결과처럼 다른 블록 안에 중첩된 문서는 여전히 허용됩니다.

user 메시지의 citations는 오류를 반환합니다

user 메시지의 text 블록(search_result 블록 내부 포함)에 citations를 보내는 경우 영향을 받습니다.

2026-10-21에서는 user 메시지에 비어 있지 않은 citations 배열을 가진 text 블록을 보내는 요청이 400 오류를 반환합니다. 해당 블록에서 citations를 제거하세요. 다시 보내는 Claude의 이전 응답처럼 assistant 메시지의 text 블록에 있는 citations는 여전히 허용되며, 문서와 검색 결과에 대한 "citations": {"enabled": true} 설정도 마찬가지입니다.

샘플링 매개변수가 제거되었습니다

Messages 요청 또는 메시지 배치 요청에서 temperature, top_p 또는 top_k를 보내는 경우 영향을 받습니다.

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:

엔드포인트이전 이름새 이름
RBAC 그룹API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.: 생성, 목록 조회, 조회, 업데이트rolesrole_ids
RBAC 그룹 멤버API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.: 목록 조회 및 추가, 그리고 멤버 제거API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에 대한 응답group_idrbac_group_id
RBAC 역할API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.: 목록 조회 및 조회namedisplay_name
조직API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 및 워크스페이스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 속도 제한: 목록 조회, 그리고 워크스페이스의 속도 제한 설정API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에 대한 응답group_typegroup.type
API 키API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.: 목록 조회, 조회, 업데이트workspace_idscope (값이 다름; API 키의 workspace_id 참조)

Claude Enterprise Analytics API:

엔드포인트이전 이름새 이름
사용자별 사용량API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 및 비용API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 보고서actor.emailactor.email_address
활동 요약API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.summariesdata

속도 제한 목록 엔드포인트의 group_type 쿼리 매개변수와 API 키 목록 엔드포인트의 workspace_id 필터는 변경되지 않습니다.

API 키의 workspace_id

코드가 API 키의 workspace_id를 읽는 경우 영향을 받습니다.

2023-06-01에서 API 키의 workspace_id는 키가 바인딩된 워크스페이스의 ID이며, 기본 워크스페이스에 바인딩된 키와 하나의 워크스페이스에 바인딩되지 않은 키(모든 워크스페이스 키)의 경우 null입니다.

2026-10-21에서는 workspace_id가 제거됩니다. 대신 scope를 읽으세요. 기본 워크스페이스를 포함하여 워크스페이스에 바인딩된 키의 경우 scope.workspace_id는 해당 워크스페이스의 실제 ID이며, 모든 워크스페이스 키는 workspace_id 없이 {"type": "organization"}의 scope를 가집니다.

코드에서 null인 workspace_id를 기본 워크스페이스로 취급했다면, 대신 scope.workspace_id를 기본 워크스페이스의 ID와 비교하세요. 해당 ID를 찾으려면 include_default=true로 워크스페이스 목록 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 호출하고 이름이 "Default"인 워크스페이스를 가져오세요.

SDK 및 CLI 변경 사항

이전 SDK 및 CLI 버전은 모든 요청에 anthropic-version: 2023-06-01을 보냈습니다. 2026-10-21로 전환에 나열된 버전은 Amazon Bedrock 및 Google Cloud 클라이언트를 포함하여 2026-10-21을 보냅니다. 호환성을 깨는 변경 사항의 변경 사항도 이들에 적용됩니다. 제거된 매개변수와 이전 필드 이름은 SDK의 타입과 CLI의 플래그 및 출력에서도 사라졌습니다.

MessageParam은 역할마다 하나의 타입을 가진 union입니다

이전 버전에서 MessageParam은 모든 역할에 대한 하나의 타입이었습니다. 이제 각 역할은 고유한 타입을 가집니다: UserMessageParam, AssistantMessageParam, SystemMessageParam. BetaMessageParam도 같은 방식으로 BetaUserMessageParam, BetaAssistantMessageParam, BetaSystemMessageParam으로 나뉩니다. SDK가 보내는 요청은 이전과 동일한 필드와 값을 가집니다.

{"role": "user", "content": "Hello"}와 같이 dict 리터럴로 작성한 메시지는 변경할 필요가 없습니다.

v1에서 anthropic.types.MessageParam은 하나의 TypedDict였습니다. v2에서는 세 타입의 union이며, anthropic.types.beta.BetaMessageParam은 해당하는 세 타입의 union입니다. 두 이름 모두 list[MessageParam]과 같은 어노테이션에서는 여전히 작동합니다.

이제 두 이름 중 하나를 호출하면 TypeError가 발생하며, 타입 검사기도 이를 표시합니다. 메시지를 dict로 작성하세요:

# 변경 전
message = MessageParam(role="user", content="Hello")

# 변경 후
message: MessageParam = {"role": "user", "content": "Hello"}

두 이름 중 하나를 서브클래싱해도 TypeError가 발생합니다. UserMessageParam과 같이 해당 역할의 타입을 서브클래싱하세요.

나머지 변경 사항은 타입 검사에만 영향을 줍니다. role이 둘 이상의 역할을 가질 수 있는 변수인 dict는 union의 어떤 타입과도 일치하지 않으므로, dict를 한 번에 하나의 역할에 대해 만드세요:

# 변경 전
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}

다음 두 가지는 BetaMessageParam에만 적용됩니다:

  • clear_at과 output_config는 BetaSystemMessageParam의 키이므로, 사용자 메시지나 어시스턴트 메시지에는 이 키를 사용할 수 없습니다.
  • BetaSystemMessageParam에서 content는 선택 사항이므로 pyright가 message["content"]를 보고합니다. message.get("content")로 읽거나, 먼저 message["role"]이 "system"이 아닌지 확인하세요.

값이 하나인 enum은 상수입니다

이 변경은 C#, Go, Java, PHP, Ruby SDK와 하나의 CLI 플래그에 영향을 줍니다. 이전 버전에서는 하나의 값만 가질 수 있는 필수 필드가 단일 멤버를 가진 고유한 enum 타입을 가졌습니다. 이제 이러한 필드는 상수이며, enum 타입은 제거되었습니다. SDK가 보내고 읽는 JSON은 동일합니다.

ant beta:sessions:resources add에서 --type은 선택 사항입니다. 그곳에서 --type이 가질 수 있는 값은 file뿐이므로 v2가 이를 대신 보냅니다. 여전히 --type file을 전달하는 명령도 계속 작동하므로 변경할 것이 없습니다.

도구 러너에서 클라이언트 측 압축이 제거됨

이 변경은 TypeScript 및 Ruby SDK에 영향을 줍니다. 도구 러너의 클라이언트 측 압축은 제거되고 “server-side compaction”(서버 측 압축)으로 대체됩니다. 서버 측 압축은 클라이언트의 추가 요청 대신 API 내부에서 대화를 요약합니다.

compactionControl 옵션과 @anthropic-ai/sdk/lib/tools/CompactionControl 모듈은 제거되었습니다. 이 옵션은 v0.129.0에서 작동을 멈췄으며, 전달하면 AnthropicError가 발생했습니다. 도구 러너의 매개변수 타입에 포함되어 있지 않으므로 TypeScript는 이를 알 수 없는 속성으로 보고합니다.

토큰 임계값에서 자동 압축을 계속하려면:

// 변경 전
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 } }]
  }
});

대화를 언제 압축할지 직접 결정하려면 runner.compactBeforeNextTurn()을 호출하세요.

트리거 임계값은 최소 50,000 토큰이어야 합니다. 다른 옵션(pause_after_compaction, 사용자 지정 instructions)은 압축을 참조하세요.

Text Completions가 제거됨

레거시 Text Completions API는 TypeScript, Go, Java, Ruby SDK와 CLI에서 제거되었습니다. 최신 모델과 기능은 이를 지원하지 않습니다. 대신 Messages API를 사용하세요.

베타가 아닌 Models 메서드에서 betas가 제거됨

베타가 아닌 Models 메서드는 더 이상 betas를 받지 않으며, ant models 명령은 더 이상 --beta를 받지 않습니다. 베타 헤더를 보내려면 client.beta.models에서 같은 메서드를 호출하거나, CLI에서는 ant beta:models를 사용하세요. SDK에서 이 메서드들은 BetaModelInfo를 반환하며, 베타가 아닌 메서드는 ModelInfo를 반환합니다.

client.models.retrieve()와 client.models.list()는 더 이상 betas를 받지 않으며(전달하면 TypeError가 발생하고 타입 검사기도 이를 표시합니다), anthropic.types.ModelListParams에는 더 이상 betas 키가 없습니다.

# 변경 전
page = client.models.list(betas=[beta])

# 변경 후
page = client.beta.models.list(betas=[beta])

API 키가 Authorization: Bearer로 전송됨

SDK와 CLI는 API 키를 X-Api-Key 헤더 대신 Authorization: Bearer <key>로 보냅니다. 따라서 X-Api-Key를 읽거나 설정하는 프록시 또는 게이트웨이를 Authorization을 사용하도록 변경하거나, 키를 X-Api-Key로 직접 보내세요. 또한 미들웨어, 로그 필터, 테스트 스텁 등 자체 프로그램에서 X-Api-Key를 읽는 코드도 변경하세요. Claude API는 두 헤더 중 어느 쪽의 키든 받습니다.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Authorization은 auth_token이 이미 사용하는 헤더입니다.

이는 Anthropic 및 AsyncAnthropic의 api_key 인수와 ANTHROPIC_API_KEY 환경 변수, 그리고 AnthropicAWS의 api_key와 ANTHROPIC_AWS_API_KEY에 적용됩니다. AnthropicFoundry는 여전히 키를 x-api-key로 보내며, AnthropicBedrockMantle은 이미 bearer 토큰을 보냈습니다.

프록시 또는 게이트웨이가 X-Api-Key를 읽는 경우

HTTP 클라이언트의 auth 함수로 키를 다시 옮기세요. 이 함수는 재시도를 포함하여 클라이언트가 보내는 모든 요청에서 실행됩니다.

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

AsyncAnthropic은 http_client=DefaultAsyncHttpxClient(auth=send_x_api_key)에서 같은 함수를 받습니다.

요청에서 X-Api-Key를 설정하거나 제거한 경우

이 변경은 Python, TypeScript, Go, PHP, Ruby SDK에 영향을 줍니다.

요청이 인증 토큰만 보내도록 X-Api-Key를 제거했다면, 해당 코드를 변경하는 대신 삭제하세요. Authorization을 제거하면 토큰이 제거되기 때문입니다. 클라이언트는 하나의 자격 증명을 보유하므로, 그것이 토큰인지 확인하세요: 코드에서 아무것도 전달하지 않고 ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN이 모두 설정되어 있으면, 클라이언트는 키를 사용합니다.

요청에서 키를 제외하기 위해 extra_headers={"X-Api-Key": omit}를 전달하는 코드는 더 이상 그렇게 동작하지 않습니다. 대신 extra_headers={"Authorization": omit}를 전달하세요.

extra_headers={"X-Api-Key": other_key}는 더 이상 클라이언트의 키를 대체하지 않으며, 두 키가 모두 전송됩니다. 하나의 요청에 다른 키를 보내려면 extra_headers={"Authorization": f"Bearer {other_key}"}를 전달하세요.

클라이언트는 하나의 자격 증명을 보유함

이제 API 키와 인증 토큰이 헤더를 공유하므로, SDK 클라이언트는 하나의 자격 증명을 보유합니다. 코드에서 아무것도 전달하지 않으면 자격 증명 우선순위 순서를 따릅니다.

v1은 클라이언트가 API 키와 인증 토큰을 모두 가지고 있을 때 각각 고유한 헤더에 담아 둘 다 보냈습니다. 자격 증명은 api_key, auth_token, credentials, config, profile 중 하나입니다.

  • 최대 하나만 전달하세요. 생성자에서, 또는 한 번의 copy()나 with_options() 호출에서 둘 이상을 전달하면 ValueError가 발생합니다. None은 세지 않습니다. v1은 TypeError를 발생시켰으며, credentials, config, profile 중 두 개를 전달한 경우에만 발생시켰습니다.
  • 전달한 것만 사용됩니다. v1과 마찬가지로 클라이언트는 환경이나 디스크에서 다른 자격 증명을 찾지 않습니다.
  • 아무것도 전달하지 않으면, 다음 중 설정된 첫 번째 항목만 사용됩니다: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_PROFILE이 지정하는 프로필, workload identity federation 변수, 디스크의 활성 프로필(active_config 파일이 지정하는 프로필, 없으면 default). 앞의 두 항목이 모두 설정되어 있으면 클라이언트는 경고를 한 번 기록합니다. v1은 ANTHROPIC_CONFIG_DIR이 설정되었거나 active_config 파일이 존재할 때 federation 변수보다 활성 프로필을 먼저 사용했습니다. 계속 활성 프로필을 사용하려면 ANTHROPIC_PROFILE을 설정하세요.
  • copy()와 with_options()는 교체합니다. 전달한 자격 증명은 종류에 관계없이 클라이언트의 자격 증명을 교체합니다. 이전 자격 증명의 구성 또는 프로필에서 온 기본 URL과 헤더는 함께 제거되며, 새 자격 증명의 것이 사용됩니다. 직접 전달한 기본 URL은 유지됩니다.
client = Anthropic(api_key=key, auth_token=token)

# 이전: `X-Api-Key: <key>`와 `Authorization: Bearer <token>`을 모두 전송함
# 이후: `ValueError`가 발생함

플랫폼 클라이언트는 자체 규칙을 유지합니다. AnthropicAWS는 오류 없이 api_key와 함께 auth_token을 받으며, 키를 보냅니다.

자세한 내용은 _client.py에 있는 Anthropic.__init__과 Anthropic.copy의 docstring을 참조하세요.

게이트웨이용 토큰과 그 뒤의 API용 키처럼 둘 다 보내는 방식에 의존했다면, 토큰을 auth_token으로 전달하고 default_headers에 X-Api-Key를 설정하세요. 게이트웨이가 요청을 전달하기 전에 자체 Authorization 헤더를 제거하도록 하세요. Claude API는 요청마다 하나의 자격 증명을 기대합니다.

하나의 SDK 또는 CLI에만 해당하는 변경 사항

이 변경 사항은 각각 하나의 SDK 또는 CLI에만 영향을 줍니다.

--api-key와 --auth-token이 제거되었습니다. 명령줄의 값은 셸 기록과 프로세스 목록에 노출되므로, ant는 더 이상 API 키나 인증 토큰을 플래그 값으로 받지 않습니다. 두 플래그 모두 v1.27.0부터 지원 중단 경고를 출력해 왔습니다. 여전히 이 중 하나를 전달하는 명령은 flag provided but not defined와 함께 중단됩니다.

제거됨대신 사용
--api-key <key>ANTHROPIC_API_KEY, --api-key-stdin, 또는 ant auth login
--auth-token <token>ANTHROPIC_AUTH_TOKEN 또는 --auth-token-stdin
# 변경 전
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

--api-key-stdin과 --auth-token-stdin은 표준 입력 전체를 읽으므로, 이 중 하나를 사용하는 명령은 요청 본문을 플래그에서 가져옵니다.

ant auth status, ant apply의 첫 실행 프롬프트, 그리고 여러 인증 소스에 대한 안내는 이제 이러한 자격 증명을 ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN으로 표시합니다. 이전에는 --api-key / ANTHROPIC_API_KEY와 --auth-token / ANTHROPIC_AUTH_TOKEN을 출력했습니다.

라이선스가 Apache 2.0으로 변경되었습니다

2026-10-21로 전환 아래의 버전부터 SDK와 CLI는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 이전 버전은 MIT License를 유지합니다. 코드 변경은 필요하지 않습니다. 종속성의 라이선스를 추적하고 있다면 해당 항목을 업데이트하세요.

  • 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 아티팩트에 적용됩니다.

이 페이지가 도움이 되었나요?