docs(models): pin request version and header contract sources

This commit is contained in:
Agent Workbench Dev
2026-11-07 14:53:51 +08:00
parent c7d1ad5e8a
commit 337d1bc922
11 changed files with 829 additions and 0 deletions
+1
View File
@@ -282,3 +282,4 @@ docs/live-delivery-ab-evidence/** binary
docs/live-delivery-ab-offline.json -text
docs/live-delivery-ab-index.json -text
docs/live-delivery-ab-shadow.json -text
tests/fixtures/model-request-contract/** -text -whitespace
+13
View File
@@ -0,0 +1,13 @@
# M2 第四批:请求版本、头与指纹
2026-11-07,基线 `c7d1ad5e8af79e527840f0c2c866e224ac3115b4`,既有GitAtlas分支逐SHA一致、工作树干净。承接I15,完成I14的现有三协议请求契约;I12非提示字段/版本指纹与原前缀观察分开。I09缓存块、I11跨Run亲和/状态和I27/I28 CI仍各自验收,不据请求头透传称全部厂商适配完成。
1. [complete] 官方OpenAI API Overview、Anthropic overview/versioning/beta与既有DeepSeek原件11份/480878字节逐SHA固定。迁移页200地区重定向原件标为拒采,不能作正文已读;版本历史明确新版采样三字段删除且2023-06-01仍在历史。见MODEL-REQUEST-CONTRACT.md与新根source-review.json。
2. [in_progress] 纯版本/头/路径契约与来源、现有凭据引用、额外非凭据头;新官方默认与已有连接版本分开,原生JSON不删除/改写,未知版本/beta透传。冻结Run/成员实际设置、目录同源身份与旧快照兼容,认证/端点变化和单纯版本/参数变化分开。
3. [pending] 每次实际请求记录已准备的头/版本/端点、去凭据指纹、原body SHA、响应版本及source,不冒称整个HTTP原字节。原ordered-prefix v1/v2保留,新增指纹只观察字段变化、不声称供应商缓存命中。
4. [pending] 相关单元与实际自有HTTP/JSON/SSE/错误/重定向、目录、混合池成员与保存/恢复;独立冻结构建、网页/实际Electron宽窄屏/三配色与已有原生参数流程,逐输入/编译/旧原件核对。
5. [pending] 回顾、限定本地提交与授权既有GitAtlas普通增量推送;准确保留首失败与未验证事项。下一缓存块/亲和/状态、CI,再M3真实迁移增量和新处理器回退。
不新增本地token、头数量/大小额度或审批停顿;HTTP/JSON格式与凭据字段各自管理,上游语义错误保留一次原响应,不自动改版本重放。默认unrestricted/passthrough/preserve和持久ask/auto/full保持。公开文档调用不是模型请求。
本批不委派、不读真实Key、不请求真实模型、不写正式数据/配置、不发行/安装/重启、不续旧实验/用户工程。I13与I15封存根只读、不追加;W/AD/AE/AG网络/unknown/重复读取、R/W预留边界与Purge收益unknown保留。
+23
View File
@@ -0,0 +1,23 @@
# 模型请求契约
本批对应 I14/I12,以实际发送的 API 版本、认证、请求头、路径与非提示参数为范围。模型注册表资料版本与 API 请求版本分别管理;旧 ordered-prefix v1/v2 的方法和原 SHA 保持。
## 官方依据
来源固定在 [SOURCE.json](../tests/fixtures/model-request-contract/SOURCE.json),11 份有效资料共 480878 字节,其中 7 份 DeepSeek 原件引用此前已提交的固定来源,不重复下载。各正文 SHA、获取表示和日期逐项保存。
- [Anthropic 版本](https://platform.claude.com/docs/en/api/versioning):必须发送 anthropic-version,当前推荐 2026-10-21;2023-06-01 仍在版本历史。新版拒绝 temperature、top_p、top_k、assistant 直接 document、user 非空 citations 等列明用法。
- [Anthropic 概览](https://platform.claude.com/docs/en/api/overview):推荐 Authorization Bearer,仍支持 x-api-key;新官方连接采用可靠官方默认,已有连接保留原默认。
- [Anthropic Beta](https://platform.claude.com/docs/en/api/beta-headers):用户显式选择,多个值用逗号组成一个头;未知或不相容 beta 由上游返回原错误,不自动移除或换版重放。
- [OpenAI 概览](https://developers.openai.com/api/reference/overview):Bearer;组织、项目、客户端请求 ID 是可选头;响应 openai-version 当前 2020-10-01,与注册表版本无关。官方建议的头大小与客户端 ID 长度不变成本工作台新增的本地拦截额度。
- [DeepSeek Messages](https://api-docs.deepseek.com/api/create-message.md):版本头可选,x-api-key/Bearer 均支持。按 DeepSeek 自身契约处理,不能套用 Anthropic 全部必填条件。
单独迁移页的一次获取返回 HTTP 200,但最终地址是 claude.com/app-unavailable-in-region,正文是地区不可用页面。该原件和原获取记录保留;SOURCE 将其明确标成 accepted=false,不作为迁移文档或配置依据。当前只依据成功取得的版本历史中明确列出的变更。
## 实现范围与回顾
连接请求设置与原生 JSON 分开。保留版本/beta/额外头/认证和模型及目录路径;Run 与每个池成员各自冻结有效设置,实际选中成员决定发送契约。凭据仍由现有独立 Key 管理,自定义鉴权头引用凭据;普通版本/beta/非鉴权头编辑不重新加密已有 Key。
每次物理尝试保留 body 原 JSON SHA;另记录准备提交给 fetch 的去凭据头、方法、端点、版本、绑定和非提示参数指纹。明确该记录的规范化/脱敏表示,不称 HTTP 原字节;相同指纹只说明观察字段相同,缓存命中、真实兼容和工程收益仍由上游实际结果独立证明。
默认 unrestricted/passthrough/preserve 与持久 ask/auto/full 保持。不改用户原生参数、不自动换线/换版本/重放失败请求。不请求真实模型或读取真实 Key、不写正式数据/配置或部署;历史网络异常、unknown、重复读取、R/W 边界与 Purge 收益 unknown 保留。
+4
View File
@@ -1,5 +1,9 @@
# 统一执行进度
I14接续来源复核:工作树仅原计划/progress与新fixture;11有效资料480878字节逐SHA一致。迁移页一次HTTP200实际跳到地区不可用页面,原记录与正文保留,追加复核将其accepted=false并明确不作为官方迁移正文。添加fixture原字节Git属性;旧I13/I15封存根未写。恢复中几次过量读取/猜错只读文件路径记录为调查失误,无产品或正式写入;下一核心契约。
M2第四批开始:c7d1ad5e干净且GitAtlas逐SHA一致,I14来源实际已取OpenAI API Overview及Anthropic overview/versioning/beta(200);最新2026-10-21删除采样三参数,2023-06-01仍有官方历史记录。新官方默认/原连接版本分开,原生参数不偷偷删改。API文档源保存在新的m2-request-contract根,I15旧根不追加;初读又有一个猜错planner文件路径与过量输出,只作调查错误记录。尚无本批产品改动、真实Key/模型/正式操作。
M2 I15普通增量推送完成:GitAtlas同分支3278c185→bf07e66d,0cbf14a2/ba4b4491/b5aaf1f7与验收逐SHA一致,5688原件和23当前链接只读复核通过。回执docs/gitatlas-m2-official-registry-push.json随完成接续最后提交再普通推送核对,不追加封存根或递归回执。下一新基线推进I14/缓存与状态、CI,正式和真实Key/模型/历史unknown不动。
M2 I15源码ba4b4491/b5aaf1f7已提交,5688份1037272654字节MANIFEST固定;50 Git blob、858输入/29编译/74runtime、两端各6组/7图通过。封存根只读,后续核对另存。QA/接续文档patch首次因猜错Tianshu/findings标题未应用,已按实读标题纠正,不记产品失败。正在文档核对/提交与GitAtlas普通增量推送,随后新根推进I14和缓存/状态、CI;不重跑旧样本/正式或触真实Key。
+2
View File
@@ -1,5 +1,7 @@
# Agent Workbench:核心代理能力研究与产品计划
M2第四批I14/I12从c7d1ad5e干净/远端一致基线开始,见[请求契约计划](docs/M2-REQUEST-CONTRACT-PLAN.md)。已实际取得官方OpenAI overview与Anthropic版本/头说明,先固定来源和旧/新默认分离,再请求版本/头/路径/快照与去凭据指纹。I15原根只读,0真实Key/模型/正式写入,不委派或重启;I09/I11/CI/M3与历史unknown保持。
M2 I15阶段1–5完成:源码ba4b4491/b5aaf1f7、来源0cbf14a2和验收bf07e66d已普通增量推送,既有GitAtlas分支逐SHA一致,[回执](docs/gitatlas-m2-official-registry-push.json)随完成接续再提交。5688原件/23当前链接只读复核通过,正式/历史unknown保持;下一I14与缓存块/亲和/状态、CI,再M3。
M2 I15阶段1–4完成,源码ba4b4491/b5aaf1f7/来源0cbf14a2,见[验收](docs/QA-M2-OFFICIAL-REGISTRY.md)。858输入/291源码/29编译/74runtime、两端6组/7图、原metadata/cipher/存储JSON快照exact,5688原件只读封存。首候选62/62与最终core/server/shared输入相同,UI补强独立build-6验收,原失败不改。阶段5文档/授权GitAtlas普通增量推送收尾;下一I14版本/头/指纹与缓存块/亲和/状态、CI,M3实际迁移/回退。0真实模型/Key/正式写入,透传/持久权限/历史unknown保持。
+161
View File
@@ -0,0 +1,161 @@
{
"schemaVersion": 1,
"defaultsVersion": "2026-11-07.1",
"sources": [
{
"id": "anthropic-overview",
"provider": "anthropic",
"url": "https://platform.claude.com/docs/en/api/overview",
"checkedAt": "2026-11-07",
"file": "sources/anthropic-overview.md",
"bytes": 23918,
"sha256": "e01f368e0ced0dd2aeec56ed76810eecaf3ba470490afea4f22dfdffd858c9e2",
"originalSha256": "e01f368e0ced0dd2aeec56ed76810eecaf3ba470490afea4f22dfdffd858c9e2",
"representation": "official-markdown-response",
"scope": "full-fetched-document"
},
{
"id": "anthropic-versioning",
"provider": "anthropic",
"url": "https://platform.claude.com/docs/en/api/versioning",
"checkedAt": "2026-11-07",
"file": "sources/anthropic-versioning.md",
"bytes": 4832,
"sha256": "47b7a604ef4d29427a8b02de7404d2146359371ac2c865c06be6e34cf385f990",
"originalSha256": "47b7a604ef4d29427a8b02de7404d2146359371ac2c865c06be6e34cf385f990",
"representation": "official-markdown-response",
"scope": "full-fetched-document"
},
{
"id": "anthropic-beta",
"provider": "anthropic",
"url": "https://platform.claude.com/docs/en/api/beta-headers",
"checkedAt": "2026-11-07",
"file": "sources/anthropic-beta.md",
"bytes": 9991,
"sha256": "a5eaed2894dee4da4dc9f80f7e58383e53545b42eea69f9aa780c7048280245d",
"originalSha256": "a5eaed2894dee4da4dc9f80f7e58383e53545b42eea69f9aa780c7048280245d",
"representation": "official-markdown-response",
"scope": "full-fetched-document"
},
{
"id": "openai-overview",
"provider": "openai",
"url": "https://developers.openai.com/api/reference/overview",
"checkedAt": "2026-11-07",
"file": "sources/openai-overview.md",
"bytes": 8098,
"sha256": "23f1fae74b726b95d06dd195411b06e97c1d1356e0bbb58da54a15a8ce1f89af",
"originalSha256": "114e5a9f15c873eea13204fcf399fb5d4fa43bdddd4d36d60d6bcbee1c4fc9cf",
"representation": "official-doc-tool-markdown",
"scope": "full-fetched-document-content"
},
{
"id": "deepseek-create",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/api/create-chat-completion",
"checkedAt": "2026-11-06",
"sha256": "b43ca950bd04ae7f6f537b42e6cb729f543d942dcd848ec43ad4e9bfe059fe1f",
"file": "../official-model-registry/sources/deepseek-create.body",
"originalSha256": "b43ca950bd04ae7f6f537b42e6cb729f543d942dcd848ec43ad4e9bfe059fe1f",
"representation": "received-html-bytes",
"scope": "complete-captured-source",
"bytes": 129498,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-thinking",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/guides/thinking_mode",
"checkedAt": "2026-11-06",
"sha256": "42151b5f86827bff663a61693080a61cdbf99074dee94af756c9fce855baa7cd",
"file": "../official-model-registry/sources/deepseek-thinking.body",
"originalSha256": "42151b5f86827bff663a61693080a61cdbf99074dee94af756c9fce855baa7cd",
"representation": "received-html-bytes",
"scope": "complete-captured-source",
"bytes": 117778,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-cache",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/guides/kv_cache",
"checkedAt": "2026-11-06",
"sha256": "061c0c7055ceb96d0a522ae1829ff5f7126ff08f26af217643e371abb740a081",
"file": "../official-model-registry/sources/deepseek-cache.body",
"originalSha256": "061c0c7055ceb96d0a522ae1829ff5f7126ff08f26af217643e371abb740a081",
"representation": "received-html-bytes",
"scope": "complete-captured-source",
"bytes": 35850,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-model-list",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/api/list-models",
"checkedAt": "2026-11-07",
"sha256": "5c8a4e4fe7256742a2d11218e6b155bb7210524a048cd0a14e733bee90194723",
"file": "../official-model-registry/sources/deepseek-model-list.html",
"originalSha256": "5c8a4e4fe7256742a2d11218e6b155bb7210524a048cd0a14e733bee90194723",
"representation": "received-html-bytes",
"scope": "complete-captured-source",
"bytes": 38360,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-models",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/quick_start/pricing",
"checkedAt": "2026-11-07",
"sha256": "af6679690eb9a7838c47727bfc5ffdc4ac91c4445a0c1219741ffe00c076ece5",
"file": "../official-model-registry/sources/deepseek-models.html",
"originalSha256": "af6679690eb9a7838c47727bfc5ffdc4ac91c4445a0c1219741ffe00c076ece5",
"representation": "received-html-bytes",
"scope": "complete-captured-source",
"bytes": 27549,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-response",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/api/create-response.md",
"checkedAt": "2026-11-07",
"sha256": "5e56e45d25db47f2b6966bbb0b2471d324035c33f0c8f81eaaf8fc444e6869da",
"file": "../official-model-registry/sources/deepseek-response.md",
"originalSha256": "5e56e45d25db47f2b6966bbb0b2471d324035c33f0c8f81eaaf8fc444e6869da",
"representation": "received-document-bytes",
"scope": "complete-captured-source",
"bytes": 33870,
"reusedFrom": "0cbf14a2"
},
{
"id": "deepseek-message",
"provider": "deepseek",
"url": "https://api-docs.deepseek.com/api/create-message.md",
"checkedAt": "2026-11-07",
"sha256": "46b31d10f429910bf93ea2166537fb803cd2f49f7c5b4ad2ee4f08257b2e17e8",
"file": "../official-model-registry/sources/deepseek-message.md",
"originalSha256": "46b31d10f429910bf93ea2166537fb803cd2f49f7c5b4ad2ee4f08257b2e17e8",
"representation": "received-document-bytes",
"scope": "complete-captured-source",
"bytes": 51134,
"reusedFrom": "0cbf14a2"
},
{
"id": "anthropic-migration",
"provider": "anthropic",
"url": "https://platform.claude.com/docs/en/api/migration-2026-10-21.md",
"checkedAt": "2026-11-07T06:50:15.790Z",
"responseUrl": "https://claude.com/app-unavailable-in-region",
"status": 200,
"bytes": 306528,
"sha256": "fd17378920a311af2ee37a8b863b1b23d58092d627d8a5b95f555867e53cf7d3",
"representation": "received-html-region-redirect-body",
"scope": "unavailable-migration-document",
"file": "sources/anthropic-migration.md",
"originalSha256": "fd17378920a311af2ee37a8b863b1b23d58092d627d8a5b95f555867e53cf7d3",
"accepted": false,
"reason": "HTTP 200 redirected to claude.com/app-unavailable-in-region; not the requested official migration document."
}
]
}
@@ -0,0 +1,237 @@
---
title: Beta headers
url: https://platform.claude.com/docs/en/api/beta-headers
description: Access experimental features before they become part of the standard API with the `anthropic-beta` header or the SDK's `betas` parameter.
---
Beta headers allow you to access experimental features and new model capabilities before they become part of the standard API.
<Info>
The [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) exposes a `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->beta`) namespace for calling the API with beta features enabled.
</Info>
## How to use beta headers
To access beta features, include the `anthropic-beta` header in your API requests:
```http
POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2026-10-21
anthropic-beta: BETA_FEATURE_NAME
content-type: application/json
```
Each feature’s documentation states the exact beta name to send. The [API overview](https://platform.claude.com/docs/en/api/overview) lists the APIs in beta.
The following example sends a request with the [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) beta. The SDK takes beta names through `betas` (csharp, go: `Betas`; java: `.addBeta()`) and sends the `anthropic-beta` header for you:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: context-management-2025-06-27" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude"}
]
}'
```
```bash CLI
ant beta:messages create \
--beta context-management-2025-06-27 \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello, Claude"}'
```
```python Python
client = Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
betas=["context-management-2025-06-27"],
)
print(response.content)
```
```typescript TypeScript
const client = new Anthropic();
const msg = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
betas: ["context-management-2025-06-27"]
});
console.log(msg.content);
```
```csharp C#
var client = new AnthropicClient();
var message = await client.Beta.Messages.Create(
new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
Betas = ["context-management-2025-06-27"],
}
);
Console.WriteLine(string.Join("\n", message.Content));
```
```go Go
client := anthropic.NewClient()
message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
},
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
})
if err != nil {
panic(err)
}
fmt.Printf("%+v\n", message.Content)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello, Claude")
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.build();
BetaMessage message = client.beta().messages().create(params);
System.out.println(message.content());
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
model: Model::CLAUDE_OPUS_5_5,
betas: ['context-management-2025-06-27'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
betas: ["context-management-2025-06-27"]
)
puts(message.content)
```
</CodeGroup>
<Warning>
Beta features are experimental and may:
* Have breaking changes with notice
* Be deprecated or removed
* Have different rate limits or pricing
* Not be available in all regions
</Warning>
### Multiple beta features
To use multiple beta features in a single request, include all feature names in the header separated by commas:
```http
anthropic-beta: feature1,feature2,feature3
```
You can also send the `anthropic-beta` header more than once in the same request. The Claude API reads every `anthropic-beta` header, so the following is equivalent to the previous example:
```http
anthropic-beta: feature1
anthropic-beta: feature2
anthropic-beta: feature3
```
With the SDK, list each feature (for example, `betas=["feature1", "feature2"]` (typescript, ruby: `betas: ["feature1", "feature2"]`; php: `betas: ['feature1', 'feature2']`; csharp: `Betas = ["feature1", "feature2"]`; go: `Betas: []anthropic.AnthropicBeta{"feature1", "feature2"}`; java: `.addBeta("feature1").addBeta("feature2")`)). With the CLI, pass a single `--beta` flag with the feature names separated by commas (for example, `--beta feature1,feature2`). You can also repeat the flag (for example, `--beta feature1 --beta feature2`).
### Beta features on other platforms
Beta names are the same on every platform that accepts them, but not every platform accepts every beta. [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) take beta names in the `anthropic-beta` header, as the Claude API does. To send several betas, put their names in one header, separated by commas: Claude Models on Google Cloud (Google managed) reads only one `anthropic-beta` header and ignores the rest, so betas in the others don’t take effect.
On Amazon Bedrock, where beta names go depends on the API you call:
* [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) (`bedrock-mantle` endpoints) takes them in the `anthropic-beta` header.
* The [InvokeModel API](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) reads them from the request body, not from a header. List them in the body’s `anthropic_beta` array, one name for each element, for example `"anthropic_beta": ["feature1", "feature2"]`.
### Endpoint-specific headers
Some beta APIs are scoped to specific endpoints and require a feature-specific beta header on every request:
| Endpoints | Beta header |
| ------------------------------------------------ | --------------------------- |
| `/v1/agents`, `/v1/sessions`, `/v1/environments` | `managed-agents-2026-04-01` |
| `/v1/tunnels` | `mcp-tunnels-2026-06-22` |
| `/v1/memory_stores` and sub-resources | `agent-memory-2026-07-22` |
The SDK’s `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->beta`) namespace adds these headers automatically. Add them yourself only when making raw HTTP requests. See the [Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview), [Using agent memory](https://platform.claude.com/docs/en/managed-agents/memory), and the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#tunnels-api) for details.
Endpoint-specific headers that apply to the same endpoint aren’t always combinable. On memory store endpoints, `agent-memory-2026-07-22` replaces `managed-agents-2026-04-01`: sending both on the same request returns a `400` error. The SDK sends the correct header for each endpoint automatically.
### Version naming conventions
Beta feature names typically follow the pattern `feature-name-YYYY-MM-DD`, where the date indicates when the beta was released. Always use the exact beta feature name as documented.
## Error handling
If you use an invalid beta name, or a beta your organization doesn’t have access to, you’ll receive a `400` error response:
```json Output
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Unexpected value(s) `invalid-beta-name` for the `anthropic-beta` header. Please consult our documentation at platform.claude.com/docs or try again without the header."
},
"request_id": "req_011CcnGfC9fELffo2EALu4Wd"
}
```
## Getting help
For updates to beta features, see the [release notes](https://platform.claude.com/docs/en/release-notes/overview). For help with production issues, contact [support](https://support.claude.com/).
## Next steps
<CardGroup cols={2}>
<Card title="Errors" icon="info" href="https://platform.claude.com/docs/en/api/errors">
Understand the HTTP status codes, error response shape, and request IDs the Claude API returns, and handle errors with the SDK’s typed exceptions.
</Card>
<Card title="API overview" icon="compass" href="https://platform.claude.com/docs/en/api/overview">
Explore the Claude API’s features, including the APIs in beta.
</Card>
</CardGroup>
File diff suppressed because one or more lines are too long
@@ -0,0 +1,195 @@
---
title: API overview
url: https://platform.claude.com/docs/en/api/overview
description: Understand the Claude API's available endpoints, authentication headers, client SDKs, pagination, rate limits, and cloud platform access options.
---
The Claude API is a RESTful API at `https://api.anthropic.com` that provides programmatic access to Claude models and Claude Managed Agents.
<Note>
**New to Claude?** For direct model access, start with [Get started](https://platform.claude.com/docs/en/get-started) and [Working with Messages](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). For managed agent infrastructure, see the [Claude Managed Agents quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart).
</Note>
## Prerequisites
To use the Claude API, you need:
* A [Claude Console account](https://platform.claude.com/)
* An [API key](https://platform.claude.com/settings/keys) from the Console, or a configured [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) rule
For step-by-step setup instructions, see [Get started](https://platform.claude.com/docs/en/get-started).
## Available APIs
The Claude API includes the following APIs:
* **[Messages API](https://platform.claude.com/docs/en/api/messages/create):** Send messages to Claude for conversational interactions (`POST /v1/messages`)
* **[Message Batches API](https://platform.claude.com/docs/en/api/messages/batches/create):** Process large volumes of Messages requests asynchronously with a 50 percent cost reduction (`POST /v1/messages/batches`)
* **[Token Counting API](https://platform.claude.com/docs/en/api/messages/count_tokens):** Count tokens in a message before sending to manage costs and rate limits (`POST /v1/messages/count_tokens`)
* **[Models API](https://platform.claude.com/docs/en/api/models/list):** List available Claude models and their details (`GET /v1/models`)
* **[Files API](https://platform.claude.com/docs/en/api/files/upload):** Upload and manage files for use across multiple API calls (`POST /v1/files`, `GET /v1/files`)
* **[Skills API](https://platform.claude.com/docs/en/api/skills/create):** Create and manage custom agent skills (`POST /v1/skills`, `GET /v1/skills`)
The following APIs are in beta:
* **[Agents API](https://platform.claude.com/docs/en/managed-agents/agent-setup):** Define reusable, versioned agent configurations for Claude Managed Agents (`POST /v1/agents`, `GET /v1/agents`)
* **[Sessions API](https://platform.claude.com/docs/en/managed-agents/sessions):** Run stateful agent sessions in managed cloud sandboxes (`POST /v1/sessions`, `GET /v1/sessions/{id}/events/stream`)
* **[Environments API](https://platform.claude.com/docs/en/managed-agents/environments):** Configure sandbox templates for agent sessions (`POST /v1/environments`, `GET /v1/environments`)
For the complete API reference with all endpoints, parameters, and response schemas, explore the API reference pages listed in the navigation. To access beta features, see [Beta headers](https://platform.claude.com/docs/en/api/beta-headers).
## Authentication
For details on each authentication method and when to use it, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). Requests to the Claude API include these headers:
| Header | Value | Required |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | `Bearer <token>`, where `<token>` is your API key or a short-lived access token obtained from `POST /v1/oauth/token` through [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) | Yes, unless `x-api-key` is set |
| `x-api-key` | Your API key from Console. Legacy fallback for `Authorization`, still supported | No |
| `anthropic-workspace-id` | ID of the [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) the request runs in (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). | Required with an API key that isn’t scoped to a workspace. Optional for other API keys. A key created for a single workspace runs in that workspace when you omit the header. Not used with Workload Identity Federation tokens, which select a workspace at token exchange. |
| `anthropic-version` | API version (for example, `2026-10-21`) | Yes |
| `content-type` | `application/json` | Yes |
If you are using the [Client SDKs](https://platform.claude.com/docs/en/api/overview#client-sdks), the SDK sends the authentication, version, and content-type headers automatically; you pass `anthropic-workspace-id` yourself when your key needs it. For API versioning details, see [API versions](https://platform.claude.com/docs/en/api/versioning).
When accessing Claude through a [cloud platform](https://platform.claude.com/docs/en/api/overview#claude-api-vs-cloud-platforms), authentication is integrated with the cloud provider’s IAM system. See the platform-specific documentation for supported credential types, required headers, and authentication options.
### Getting API keys
The API is made available through the web [Console](https://platform.claude.com/). In the Console, you can use [playground](https://platform.claude.com/playground) (`platform.claude.com/playground`) to try out the API in the browser and then generate API keys on the [API keys](https://platform.claude.com/settings/keys) page (`platform.claude.com/settings/keys`). To learn how, see [Get your Claude API key](https://platform.claude.com/docs/en/get-api-key). You choose each key’s type (see [Key types](https://platform.claude.com/docs/en/manage-claude/authentication#key-types)) and its [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration) when you create it. Use [workspaces](https://platform.claude.com/settings/workspaces) in the Console to separate environments and [control spend](https://platform.claude.com/docs/en/api/rate-limits) by use case.
## Client SDKs
Anthropic provides official SDKs that simplify API integration by handling authentication, request formatting, error handling, and more.
**Benefits:**
* Automatic header management (authentication, `anthropic-version`, `content-type`)
* Type-safe request and response handling
* Built-in retry logic and error handling
* Streaming support
* Request timeouts and connection management
For a list of client SDKs, see [SDKs, CLI, and libraries](https://platform.claude.com/docs/en/cli-sdks-libraries/overview).
## Claude API versus cloud platforms
Claude is available through the first-party Claude API and through cloud platforms. Choose based on your infrastructure, feature availability, compliance requirements, and pricing preferences.
### Claude API
* **Direct access** to the latest models and features
* **Anthropic billing and support**
* **Best for:** New integrations, full feature access, direct relationship with Anthropic
### Cloud platform APIs
Access Claude through AWS, Google Cloud, or Microsoft Azure:
* **Integrated** with cloud provider billing and IAM
* **Feature availability varies by platform:** Anthropic-operated platforms include [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry); partner-operated platforms include Claude Models on Google Cloud (Google managed) and Amazon Bedrock. See each platform’s page for feature availability and timing.
* **Best for:** Existing cloud commitments, specific compliance requirements, consolidated cloud billing
| Platform | Provider | Documentation |
| ------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Models on Google Cloud (Google managed) | Google Cloud | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) |
| Amazon Bedrock | AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) |
| Claude Platform on AWS | AWS (Anthropic-operated) | [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) |
| Claude Models on Google Cloud (Anthropic managed) | Google Cloud (Anthropic-operated) | [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |
| Microsoft Foundry | Microsoft Azure (Anthropic-operated) | [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
<Note>
Claude Managed Agents is available through the first-party Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed). For feature availability across platforms, see the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
</Note>
## Request and response format
### Request size limits
The first-party Claude API enforces these request size limits:
| Endpoint | Maximum request size |
| -------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Messages, Token Counting | 128 MB |
| Message Batches API (see [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing)) | 256 MB |
| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | 500 MB |
| Sessions, Agents, Environments | 32 MB |
If you exceed these limits, you’ll receive a 413 `request_too_large` error.
<Note>
Partner-operated platforms have their own request size limits: Bedrock limits requests to 20 MB, and Claude Models on Google Cloud (Google managed) limits requests to 30 MB. Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Microsoft Foundry support Messages and Token Counting requests of up to 32 MB. Consult your platform’s documentation for current values.
</Note>
### Response headers
The Claude API includes the following headers in its responses:
| Header | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request-id` | A globally unique identifier for the request, such as `req_018EeWyXxfu5pfWkrYcMdjWG`. Include it when you contact support about a specific request. See [Request ID](https://platform.claude.com/docs/en/api/errors#request-id). |
| `anthropic-organization-id` | The ID of the organization that the API key or access token used in the request belongs to. |
| `anthropic-workspace-id` | The `wrkspc_`-prefixed ID of the [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) that the API key or access token resolved to, such as `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`, including when that is your organization’s Default Workspace. Absent when the credential doesn’t resolve to a workspace (for example, on Admin API requests) or the request fails before authentication completes. See [Identify the workspace behind an API response](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). |
For the rate limit headers, see [Response headers](https://platform.claude.com/docs/en/api/rate-limits#response-headers) in Rate limits. For examples that read a response header by name with each SDK, see [Identify the workspace behind an API response](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response).
<Note>
Claude Platform on AWS adds an AWS request ID (`x-amzn-requestid`) alongside the standard `request-id` header. See [Request IDs](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#request-ids) for the dual-ID handling pattern.
</Note>
## Pagination
List endpoints return results in pages. Most newer list endpoints use the `page` and `next_page` cursor scheme described in this section. Some use a different scheme; see the note at the end of this section. Use the `limit` query parameter to control the page size and the `page` query parameter to fetch an adjacent page. Each response includes a `data` array alongside cursor fields for navigating between pages.
| Name | Location | Description |
| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | Query parameter | Maximum number of items to return per page. |
| `page` | Query parameter | Opaque cursor from a previous response. Pass a `next_page` or `prev_page` value here to fetch the adjacent page. |
| `order` | Query parameter | Sort direction for the results (`asc` or `desc`), on list endpoints that support sorting. A `page` cursor is only valid with the `order` it was created with. |
| `next_page` | Response field | Cursor for the next page, or `null` if there are no more results. |
| `prev_page` | Response field | Cursor for the previous page on endpoints that support backward pagination (currently `GET /v1/sessions`), or `null` if you are on the first page. Other list endpoints omit the field. |
To go back a page, pass `prev_page` as the `page` parameter. `prev_page` is `null` when you’re on the first page. Not all list endpoints support `prev_page`. Only `GET /v1/sessions` returns `prev_page`; on list endpoints that do not support backward pagination, the field is absent from the response rather than `null`. For a request walkthrough, see [Listing sessions](https://platform.claude.com/docs/en/managed-agents/session-operations#listing-sessions).
The SDK provides an auto-paginating iterator that follows `next_page` for you. For example, `for session in client.beta.sessions.list()` (typescript: `for await (const session of client.beta.sessions.list())`; go: `client.Beta.Sessions.ListAutoPaging()`; java: `client.beta().sessions().list().autoPager()`; csharp: `(await client.Beta.Sessions.List()).Paginate()`; php: `$client->beta->sessions->list()->pagingEachItem()`; ruby: `client.beta.sessions.list.auto_paging_each`) walks through every session. SDK auto-pagination is forward-only; to go back a page, read `prev_page` from the response and pass it back as the `page` parameter yourself. See [SDKs, CLI, and libraries](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) for details.
<Note>
Some list endpoints use a different cursor scheme. The Message Batches API (see [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing)), the [Models API](https://platform.claude.com/docs/en/api/models/list), and several [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) endpoints take `after_id` and `before_id` query parameters instead of `page`. Their responses return `has_more`, `first_id`, and `last_id` instead of `next_page`. See the reference page for each endpoint for its exact pagination fields.
</Note>
## Rate limits and availability
### Rate limits
The API enforces rate limits and spend limits to prevent misuse and manage capacity. Limits are organized into usage tiers; your organization is placed on a tier automatically and can move to a higher tier over time. Each tier has:
* **Spend limits:** Maximum monthly cost for API usage
* **Rate limits:** Maximum number of requests per minute (RPM) and tokens per minute (TPM)
You can view your rate limits under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits) and your spend limits on the Console’s [Billing](https://platform.claude.com/settings/billing) page. For higher rate limits or a higher monthly spend cap, use **Request tier increase** on the **Rate limits** page.
For detailed information about limits, tiers, and the token bucket algorithm used for rate limiting, see [Rate limits](https://platform.claude.com/docs/en/api/rate-limits).
### Availability
The Claude API is available in [many countries and regions](https://platform.claude.com/docs/en/api/supported-regions) worldwide. Check the supported regions page to confirm availability in your location.
## Next steps
<CardGroup cols={2}>
<Card title="Messages API reference" icon="book" href="https://platform.claude.com/docs/en/api/messages/create">
Complete API specification for direct model interactions
</Card>
<Card title="Claude Managed Agents reference" icon="brain" href="https://platform.claude.com/docs/en/managed-agents/sessions">
Agents, Sessions, and Environments endpoints
</Card>
<Card title="Client SDKs" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/overview">
Python, TypeScript, C#, Go, Java, PHP, and Ruby
</Card>
<Card title="Rate limits" icon="gauge" href="https://platform.claude.com/docs/en/api/rate-limits">
Usage tiers, requesting higher limits, and the token bucket algorithm
</Card>
</CardGroup>
@@ -0,0 +1,60 @@
---
title: Versions
url: https://platform.claude.com/docs/en/api/versioning
description: "When making API requests, you must send an `anthropic-version` request header. For example, `anthropic-version: 2026-10-21`. If you are using the [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview), this is handled for you automatically."
---
For any given API version, Anthropic preserves:
* Existing input parameters
* Existing output parameters
However, Anthropic may do the following:
* Add additional optional inputs
* Add additional values to the output
* Change conditions for specific error types
* Add new variants to enum-like output values (for example, streaming event types)
Generally, if you are using the API as documented in this reference, Anthropic will not break your usage.
## Version history
Anthropic recommends using the latest API version whenever possible.
* `2026-10-21`
* [Migrating to API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21) shows how to upgrade.
* Available on the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). On [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), it’s available for Claude 4.7 and later models. For other models on Bedrock, see the [migration guide for API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21#upgrade).
* Messages API:
* A request that places a `document` block directly in an `assistant` message returns a 400 error.
* Sending a `text` block with a non-empty `citations` array in a `user` message, directly or inside a `search_result` block, returns a 400 error.
* The `temperature`, `top_p`, and `top_k` request parameters are removed. A request that sends any of them returns a 400 error on every model.
* Admin API:
* [RBAC groups](https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/list) no longer return `roles`. Use `role_ids` instead.
* [RBAC group members](https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/members/list), and the response to removing one, no longer return `group_id`. Use `rbac_group_id` instead.
* [RBAC roles](https://platform.claude.com/docs/en/api/beta/organization/rbac_roles/list) no longer return `name`. Use `display_name` instead.
* [Organization](https://platform.claude.com/docs/en/api/organization/rate_limits/list) and [workspace](https://platform.claude.com/docs/en/api/organization/workspaces/rate_limits/list) rate-limit entries, and the response to [setting a workspace’s rate limits](https://platform.claude.com/docs/en/api/organization/workspaces/rate_limits/update), no longer return `group_type`. Use `group.type` instead.
* [API keys](https://platform.claude.com/docs/en/api/organization/api_keys/list) no longer return `workspace_id`. Use `scope.workspace_id` instead, which gives the workspace’s real ID even for the Default Workspace (an all-workspaces key has no `workspace_id` in `scope`).
* Claude Enterprise Analytics API:
* The per-user [usage](https://platform.claude.com/docs/en/api/beta/organization/analytics/user_usage_report/list) and [cost](https://platform.claude.com/docs/en/api/beta/organization/analytics/user_cost_report/list) reports no longer have `actor.email`. Use `actor.email_address` instead.
* The [activity summaries](https://platform.claude.com/docs/en/api/beta/organization/analytics/summaries/list) response no longer has `summaries`. Use `data` instead.
* `2023-06-01`
* New format for [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) server-sent events (SSE):
* Completions are incremental. For example, `" Hello"`, `" my"`, `" name"`, `" is"`, `" Claude." `instead of `" Hello"`, `" Hello my"`, `" Hello my name"`, `" Hello my name is"`, `" Hello my name is Claude."`.
* All events are [named events](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#named%5Fevents), rather than [data-only events](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#data-only%5Fmessages).
* Removed unnecessary `data: [DONE]` event.
* Removed legacy `exception` and `truncated` values in responses.
* `2023-01-01`: Initial release.
@@ -0,0 +1,124 @@
# API Overview
Use this reference to look up OpenAI API endpoints, request and response
schemas, streaming events, client library methods, and shared behavior such as
authentication, errors, rate limits, and request IDs.
## Start here
1. Choose the API surface for your application:
- [Responses](https://developers.openai.com/api/reference/responses/overview) for direct model requests, tool use, audio, image, and text inputs, and stateful interactions.
- [Realtime API](https://developers.openai.com/api/docs/guides/realtime) for low-latency voice or audio sessions over WebRTC, WebSocket, or SIP. Use the [client events](https://developers.openai.com/api/reference/resources/realtime/client-events) and [server events](https://developers.openai.com/api/reference/resources/realtime/server-events) references while building sessions.
- [Administration](https://developers.openai.com/api/reference/administration/overview) for organization workflows such as users, invites, projects, API keys, and audit logs.
2. Create credentials. Use a standard [API key](https://platform.openai.com/settings/organization/api-keys) for application requests, an [Admin API key](https://platform.openai.com/settings/organization/admin-keys) for Administration endpoints, or [workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) for short-lived access tokens.
3. Install an official client library from the [libraries page](https://developers.openai.com/api/docs/libraries), or call the HTTP API directly from any environment that supports HTTP requests.
4. Make a first request with the [developer quickstart](https://developers.openai.com/api/docs/quickstart) or go straight to the [Responses create reference](https://developers.openai.com/api/reference/resources/responses/methods/create).
5. Before production, review [error codes](https://developers.openai.com/api/docs/guides/error-codes), [rate limits](https://developers.openai.com/api/docs/guides/rate-limits), and request ID logging below.
## Authentication
The OpenAI API accepts bearer credentials from API keys or from short-lived access tokens created with [workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation).
**Remember that your API key is a secret.** Don't share it with others or expose it in any client-side code such as browsers or apps. Load API keys from an environment variable or key management service on the server.
Revocations of an API key take effect within a few seconds. Most updates that
affect authentication results of an API key propagate within 15 minutes, but
can potentially take longer.
Provide API credentials with [HTTP Bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).
```bash
Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN
```
If you belong to more than one organization or access projects through a legacy user API key, pass a header to specify which organization and project to use for an API request:
```bash
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Organization: $ORGANIZATION_ID" \
-H "OpenAI-Project: $PROJECT_ID"
```
Usage from these API requests counts as usage for the specified organization and project. Find organization and project IDs in your [dashboard settings](https://platform.openai.com/settings/organization/general).
## Request headers
For reliable behavior across API paths and HTTP versions, keep the total size
of an API request's headers under 64 KiB. This budget includes the names and
values of all headers, including common headers such as `Authorization`,
`Content-Type`, and `User-Agent`, as well as any custom headers.
To leave room for required headers and headers added by intermediaries, keep
any individual custom header value and the total size of all custom header
values at 60 KiB or less. Requests with larger headers may fail before they
reach the API, so you may not receive a response or an `x-request-id`.
## Debugging requests
[Error codes](https://developers.openai.com/api/docs/guides/error-codes) describe failures returned from API responses. Inspect HTTP response headers for the unique ID of a request and rate limit details. Common response headers include:
**API meta information**
- `openai-organization`: The [organization](https://developers.openai.com/api/docs/guides/production-best-practices#setting-up-your-organization) associated with the request
- `openai-processing-ms`: Time taken processing your API request
- `openai-version`: REST API version used for this request (currently `2020-10-01`)
- `x-request-id`: Unique identifier for this API request (used in troubleshooting)
**[Rate limiting information](https://developers.openai.com/api/docs/guides/rate-limits)**
- `x-ratelimit-limit-requests`
- `x-ratelimit-limit-tokens`
- `x-ratelimit-remaining-requests`
- `x-ratelimit-remaining-tokens`
- `x-ratelimit-reset-requests`
- `x-ratelimit-reset-tokens`
- `x-ratelimit-limit-project-tokens`
- `x-ratelimit-remaining-project-tokens`
- `x-ratelimit-reset-project-tokens`
Project-token headers may be present when a project-scoped token limit applies.
**OpenAI recommends logging request IDs in production deployments** for more efficient troubleshooting with the [support team](https://help.openai.com/en/), should the need arise. Official [client libraries](https://developers.openai.com/api/docs/libraries) provide a property on top-level response objects containing the value of the `x-request-id` header.
### Supplying your own request ID with `X-Client-Request-Id`
Along with the server-generated `x-request-id`, you can supply your own unique identifier for each request via the `X-Client-Request-Id` request header. This header isn't added automatically; you must explicitly set it on the request.
When you include `X-Client-Request-Id`:
- You control the ID format (for example, a UUID or your internal trace ID), but it must contain only ASCII characters and be no more than 512 characters long; otherwise, the request will fail with a 400 error. Make this value unique per request.
- OpenAI logs this value internally for supported endpoints, including chat/completions, embeddings, responses, and more.
- In cases like timeouts or network issues when you can't get the `X-Request-Id` response header, you can share the `X-Client-Request-Id` value with the support team to look up whether OpenAI received the request and when.
**Example:**
```bash
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "X-Client-Request-Id: 123e4567-e89b-12d3-a456-426614174000"
```
## Backwards compatibility
OpenAI provides stability to API users by avoiding breaking changes in major API versions whenever reasonably possible. This includes:
- The REST API (currently `v1`)
- First-party [client libraries](https://developers.openai.com/api/docs/libraries) (released libraries adhere to [semantic versioning](https://semver.org/))
- [Model](https://developers.openai.com/api/docs/models) families (like `gpt-4o` or `o4-mini`)
**Model prompting behavior between snapshots is subject to change**.
Model outputs are by their nature variable, so expect changes in prompting and model behavior between snapshots. The best way to ensure consistent prompting behavior and model output is to use pinned model versions, and to run [evals](https://developers.openai.com/api/docs/guides/evals) for your applications.
**Backwards-compatible API changes**:
- Adding new resources (URLs) to the REST API and client libraries
- Adding new optional API parameters
- Adding new properties to JSON response objects or event data
- Changing the order of properties in a JSON response object
- Changing the length or format of opaque strings, like resource identifiers
- Adding new event types in streaming APIs
See the [changelog](https://developers.openai.com/api/docs/changelog) for a list of backwards-compatible changes and rare breaking changes.