2026-10-21에서 바뀌는 것
ClaudeDevs가 2026년 10월 21일에 올린 글은 깨지는 지점 세 가지를 꼽습니다. temperature, top_p, top_k가 Messages API에서 빠지고, assistant 턴의 문서와 user 턴의 citations는 400을 반환하며, 사용 중단된 Admin 및 Enterprise Analytics 필드 몇 개가 교체됩니다. 마이그레이션 가이드는 이 Messages 규칙을 POST /v1/messages, 토큰 집계, 그리고 2026-10-21로 만든 Message Batch의 각 요청에 적용합니다.
temperature, top_p, top_k를 보내면 그 파라미터의 기본값이어도 400이 반환됩니다. 이 파라미터를 빼면 요청은 기본값으로 샘플링하며, 여기에는 temperature 1.0이 포함됩니다. 파라미터를 비워 둔 2023-06-01 요청과 같습니다. Claude 4.7 이후 모델은 이미 그 기본값만 받고, 샘플링도 이전과 같습니다. 다른 값을 받는 모델에 대해 가이드가 든 예는 Claude Sonnet 4.6입니다. 낮춘 temperature는 그 효과를 잃고, 이를 대신하는 다른 설정은 없으며, 그 요청은 2023-06-01에 남겨 둘 수 있습니다.
assistant 메시지에 문서 블록을 직접 넣으면 400이 반환됩니다. 문서는 user 메시지에 보냅니다. 다른 블록 안에 중첩된 문서, 예를 들어 Claude가 반환한 web-fetch 도구 결과는 그대로 받습니다. citations 배열이 비어 있지 않은 user 메시지 텍스트 블록은 400을 반환하며, search_result 블록 안의 citations도 포함됩니다. 이전에 보낸 답변을 다시 보내는 경우처럼 assistant 메시지 텍스트의 citations는 그대로 받고, 문서와 검색 결과의 "citations": {"enabled": true}도 마찬가지입니다.
Admin API와 Claude Enterprise Analytics API 응답에는 표의 예전 이름이 더 이상 들어 있지 않습니다. API 키에서는 workspace_id가 빠지고, 호출 측은 scope를 읽습니다. Default Workspace에 묶인 키를 포함해 워크스페이스에 묶인 키는 그 워크스페이스의 실제 ID를 scope.workspace_id에 넣습니다. 모든 워크스페이스용 키의 scope는 {"type": "organization"}이고 workspace_id는 없습니다. 가이드는 2023-06-01에서 Default Workspace에 묶인 키와 모든 워크스페이스용 키 모두 workspace_id가 null이었다고 적습니다. null을 Default로 다루던 코드는 include_default=true로 List Workspaces를 호출해 이름이 Default인 워크스페이스와 scope.workspace_id를 비교해야 합니다. rate limit 목록 엔드포인트의 group_type 쿼리 파라미터와 API 키 목록 엔드포인트의 workspace_id 필터는 그대로입니다.
| 엔드포인트 | 예전 이름 | 새 이름 |
|---|---|---|
| RBAC 그룹: 생성, 목록, 조회, 업데이트 | roles | role_ids |
| RBAC 그룹 멤버: 목록, 추가, 그리고 멤버 제거 응답 | group_id | rbac_group_id |
| RBAC 역할: 목록과 조회 | name | display_name |
| 조직 및 워크스페이스 rate limit: 목록, 그리고 워크스페이스 rate limit 설정 응답 | group_type | group.type |
| API 키: 목록, 조회, 업데이트 | workspace_id | scope (값이 다름) |
| 사용자별 사용량 및 비용 리포트 | actor.email | actor.email_address |
| 활동 요약 | summaries | data |
클라이언트를 바꿔야 하는 경우
ClaudeDevs는 Anthropic SDK와 ant CLI의 새 메이저 버전이 글이 올라온 날인 2026년 10월 21일에 나왔고 기본값이 2026-10-21이라고 합니다. 마이그레이션 가이드는 그 클라이언트 릴리스의 날짜를 적지 않습니다. SDK는 해당 메이저가 나올 당시의 API 버전을 보내고, 언어별로 표시된 버전이 2026-10-21을 보내는 첫 버전이며, 여기에는 Amazon Bedrock과 Google Cloud 클라이언트가 포함된다고 적습니다. 그 이전 SDK와 CLI 버전은 anthropic-version 2023-06-01을 보냈습니다. 가이드가 지목한 Python 업그레이드는 anthropic 2.0.0입니다. 다른 언어는 그 언어 탭에 표시된 버전을 가리킵니다.
Amazon Bedrock에서 2026-10-21은 Claude 4.7 이후에만 쓸 수 있습니다. Claude on Amazon Bedrock에 Opus 4.6 이하로 적힌 더 오래된 Bedrock 모델 호출은, 그 호출이 Claude 4.7 이후 모델을 쓰기 전까지 지금 쓰는 SDK 버전이나 지금 보내는 버전 헤더에 둡니다. 같은 가이드는 그 SDK 버전의 Google Cloud 클라이언트가 2026-10-21을 보낸다고 적습니다.
SDK와 CLI는 API 키를 X-Api-Key 대신 Authorization: Bearer로 보냅니다. Claude API는 어느 헤더의 키든 받으므로, API에 직접 말하는 프로그램은 이 교체만으로는 바꿀 것이 없습니다. X-Api-Key를 읽거나 설정하는 프록시나 게이트웨이는 Authorization을 쓰거나, 호출 측이 X-Api-Key를 계속 보낼 수 있습니다. 가이드는 AnthropicFoundry가 여전히 키를 x-api-key로 보낸다고 적습니다.
API 키와 인증 토큰이 이제 헤더를 공유하므로 SDK 클라이언트는 자격 증명을 하나만 갖습니다. Python에서는 생성자에 둘 이상을 넣거나 한 번의 copy() 또는 with_options() 호출에 둘 이상을 넣으면 ValueError가 납니다. None을 넘기는 것은 자격 증명으로 치지 않습니다. 게이트웨이 토큰과 API 키를 함께 보내려면 토큰은 auth_token으로 넘기고 default_headers에 X-Api-Key를 설정한 뒤, 게이트웨이가 전달 전에 자신의 Authorization 헤더를 제거하게 합니다. Claude API는 요청마다 자격 증명 하나를 기대하기 때문입니다. Python, TypeScript, Go, PHP, Ruby SDK에서는 X-Api-Key를 빼는 extra_headers가 더 이상 요청에서 키를 빼지 않습니다. 가이드가 제시한 Python 대체는 extra_headers={"Authorization": omit}입니다.
ant CLI는 --api-key와 --auth-token을 뺍니다. 플래그 값이 셸 기록과 프로세스 목록에 보이기 때문입니다. 두 플래그는 v1.27.0부터 사용 중단 경고를 출력해 왔습니다. 어느 쪽이든 아직 넘기는 명령은 "flag provided but not defined."에서 멈춥니다. 키는 ANTHROPIC_API_KEY, --api-key-stdin, 또는 ant auth login을 씁니다. 토큰은 ANTHROPIC_AUTH_TOKEN 또는 --auth-token-stdin을 씁니다.
- Text Completions는 TypeScript, Go, Java, Ruby SDK와 CLI에서 빠지며, ant completions create도 포함됩니다. 가이드는 Messages API를 쓰라고 합니다.
- TypeScript와 Ruby 도구 러너는 클라이언트 측 compaction 대신 서버 측 compaction을 씁니다. input token 트리거는 50,000 이상이어야 합니다. 수동 호출은 compactBeforeNextTurn()입니다.
- 비베타 Models 메서드는 더 이상 betas를 받지 않고, ant models 명령도 --beta를 받지 않습니다. 베타 헤더는 client.beta.models 또는 ant beta:models로 보내며, 반환 타입은 BetaModelInfo입니다.
- MessageParam은 이제 UserMessageParam, AssistantMessageParam, SystemMessageParam의 유니온입니다. BetaMessageParam도 같은 방식으로 나뉩니다. SDK가 보내는 JSON의 필드와 값은 그대로입니다. Python에서 {"role": "user", "content": "Hello"} 같은 dict 리터럴은 바꿀 필요가 없습니다. MessageParam()이나 BetaMessageParam()을 호출하거나 둘 중 하나의 이름을 서브클래싱하면 TypeError가 납니다. UserMessageParam처럼 역할에 해당하는 타입을 서브클래싱합니다.
- C#, Go, Java, PHP, Ruby SDK에서 값이 하나뿐인 필수 필드는 이제 상수이고, 멤버가 하나인 enum 타입은 사라집니다. SDK가 보내고 읽는 JSON은 그대로입니다. CLI에서 ant beta:sessions:resources add의 --type은 선택이며, 받을 수 있는 값은 file뿐이고, --type file을 아직 넘기는 명령은 그대로 동작합니다.
바꾸는 방법
SDK를 쓰지 않는 호출자는 anthropic-version 헤더를 2026-10-21로 설정합니다. SDK 호출자는 가이드가 자기 언어에 보여주는 버전으로 올립니다. Python에서 이름이 적힌 단계는 anthropic 2.0.0입니다. 가이드의 순서는 버전을 바꾸고, 해당하는 각 호환 파괴 변경과 새 SDK 또는 CLI가 요구하는 것을 코드에 반영한 뒤, 릴리스 전에 연동을 2026-10-21에 맞춰 테스트하는 것입니다. 버전 업그레이드는 그 수정과 함께 릴리스합니다.
ClaudeDevs는 Claude Code의 /claude-api 스킬이나 마이그레이션 가이드를 가리킵니다. 2026년 10월 21일자 Claude Code 2.1.307은 Claude API 코드를 API 버전 2026-10-21로 옮기는 /claude-api api-version을 추가합니다.
이 SDK와 CLI 버전은 Apache License 2.0입니다. 이전 버전은 MIT를 유지합니다. 가이드는 라이선스 변경에 코드 수정이 필요 없다고 하며, 의존성 라이선스를 추적한다면 그 항목을 갱신하라고 합니다. 1.0.0 릴리스는 TypeScript 플랫폼 패키지와 그 외 C# 패키지의 라이선스 변경입니다. Java 변경은 모든 com.anthropic 아티팩트를 덮습니다. 가이드에서 Python의 API 버전 핀은 anthropic 2.0.0으로 남아 있습니다.
아직 열려 있는 것
ClaudeDevs 글과 마이그레이션 가이드는 2023-06-01이나 2026-10-21의 가격, 할당량 변경, 종료일을 제시하지 않습니다. ClaudeDevs는 2023-06-01이 사용 중단되지 않았다고 합니다. 가이드의 관련 지시는, 기본값이 아닌 샘플링 값이 필요한 요청은 2023-06-01에 두라는 것입니다. 버전을 더 자주 내겠다는 ClaudeDevs의 계획은 일정, 다음 버전 id, 이후 버전을 요구할 모델을 밝히지 않습니다.
출처
함께 본 출처
자료 및 작성 기준
이 브리프는 2026년 10월 21일에 공개된 ClaudeDevs 글, API 버전 2026-10-21용 Anthropic 마이그레이션 가이드, 2026년 10월 21일자 Claude Code 2.1.307 변경 기록을 근거로 합니다. 가이드와 변경 기록은 2026년 10월 22일에 확인했습니다. 제공 여부, 2023년 이후 첫 공식 버전이라는 설명, 버전을 더 자주 내겠다는 계획, 2023-06-01은 사용 중단되지 않았다는 문장, 같은 날의 SDK 및 ant CLI 릴리스는 ClaudeDevs의 발언입니다. 요청과 클라이언트 동작은 마이그레이션 가이드가 말하는 내용입니다. 가격, 할당량, 종료일, 실제 API 호출, 별도의 Bedrock 모델 목록은 다루지 않았습니다. 가이드는 Python에 anthropic 2.0.0을 지목하고, 다른 언어는 각 언어에 표시된 버전을 가리킵니다.