One read of Claude Developer Platformapi-20261021T193714Z
242 pages moved out of 808 read.
Pages moved
242
significant first
Pages read
808
in this capture
Captured
19:37 UTC
Corpus hash
851c97e9b6f0
corpus-hash
What this read moved
101-125 of 242, page 5 of 10This capture is too large to show at once. Changes 101-125 of 242 are below, significant first; the rest are on the following screens.
build-with-claude/vision Changed · +18 / -18 lines
from line 1
11---
22title: Vision
33url: https://platform.claude.com/docs/en/build-with-claude/vision
4description: Claude's vision capabilities allow it to understand and analyze images, opening up exciting possibilities for multimodal interaction.
4description: Claude's vision capabilities allow it to process and analyze images, opening up exciting possibilities for multimodal interaction.
55---
66
77This guide describes how to send images to Claude, the limits and costs that apply, and where to find guidance for [coordinate-based workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates).
from line 13
1313Use Claude's vision capabilities through:
1414
1515* [claude.ai](https://claude.ai/). Upload an image like you would a file, or drag and drop an image directly into the chat window.
16* [Playground](https://platform.claude.com/playground) in the Claude Console. Add images directly to any User message block.
16* [Playground](https://platform.claude.com/playground) in the Claude Console. Add images directly to any **User** message block.
1717* API request. See the following examples.
1818
1919On the API, provide images to Claude as `image` content blocks using one of three source types:
from line 1219
12191219
12201220### Request limits
12211221
1222The maximum number of images per message or request is:
1222The maximum number of images for each message or request is:
12231223
1224* 20 per message on [claude.ai](https://claude.ai/).
1225* 100 per request on the API, for models with a 200k-token context window.
1226* 600 per request on the API, for all other models.
1224* 20 for each message on [claude.ai](https://claude.ai/)
1225* 100 for each request on the API, for models with a 200k-token context window
1226* 600 for each request on the API, for all other models
12271227
1228The maximum dimensions per image are 8000x8000 px.
1228The maximum dimensions for each image are 8000x8000 px.
12291229
12301230If a single API request contains more than 20 images, a stricter per-image dimension limit applies to every image in that request. All `image` blocks in the request count toward this threshold, including images from earlier conversation turns that you resend and images nested inside `tool_result` content (for example, screenshots returned to the computer use tool). On Amazon Bedrock and Google Cloud, document blocks such as PDFs also count toward this threshold. Images exceeding the stricter limit are rejected with an `invalid_request_error` whose message references "many-image requests" and states the current limit in pixels. To stay under the limit on all platforms, either resize each image so that neither dimension exceeds 2000 px, or keep the request to 20 or fewer image and document blocks.
12311231
from line 1247
12471247
12481248### Resolution and token cost
12491249
1250Claude views images in patches instead of pixels. Each patch is a 28×28-pixel block of the image, referred to as a visual token. An image, therefore, costs `⌈width / 28⌉ × ⌈height / 28⌉` visual tokens.
1250Claude processes images in patches instead of pixels. Each patch is a 28×28-pixel block of the image, referred to as a visual token. An image, therefore, costs `⌈width / 28⌉ × ⌈height / 28⌉` visual tokens.
12511251
12521252Each model has a maximum native image resolution, expressed as a long-edge limit and a visual-token limit. Images larger than either limit are downscaled before processing; see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images) for the exact rule. The exception is screenshots and zoom images that you return to the [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) toolsets: the API rejects a `tool_result` image that exceeds the model's limits with a validation error instead of downscaling it, so resize those images in your application before returning them. To have any other oversized image rejected with an error instead of downscaled, set the image block's [`transformations` field](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error).
12531253
from line 1288
12881288
12891289## Coordinates and bounding boxes
12901290
1291For bounding boxes, points, and pixel coordinates, see [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates). Claude returns absolute pixel coordinates relative to the image it sees after resizing; that guide covers how Claude resizes and pads images and how to pre-resize or rescale so coordinates line up with your original image.
1291For bounding boxes, points, and pixel coordinates, see [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates). Claude returns absolute pixel coordinates relative to the image it processes after resizing; that guide covers how Claude resizes and pads images and how to pre-resize or rescale so coordinates line up with your original image.
12921292
12931293***
12941294
12951295## Limitations
12961296
1297Although Claude's image understanding capabilities are cutting-edge, there are some limitations to be aware of:
1297Although Claude's image understanding capabilities are advanced, there are some limitations to be aware of:
12981298
1299* **People identification:** Claude [cannot be used](https://www.anthropic.com/legal/aup) to name people in images and refuses to do so.
1299* **People identification:** Claude cannot be used to name people in images and refuses to do so (see the [Usage Policy](https://www.anthropic.com/legal/aup)).
13001300* **Accuracy:** Claude might hallucinate or make mistakes when interpreting low-quality, rotated, or very small images under 200 pixels.
13011301* **Spatial reasoning:** Claude's coordinate and localization outputs are approximate. Follow the guidance in [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates) and verify outputs before relying on them.
13021302* **Counting:** Claude can give approximate counts of objects in an image but might not always be precisely accurate, especially with large numbers of small objects.
13031303* **AI-generated images:** Claude cannot determine whether an image is AI-generated and might be incorrect if asked. Do not rely on it to detect fake or synthetic images.
1304* **Inappropriate content:** Claude does not process inappropriate or explicit images that violate the [Acceptable Use Policy](https://www.anthropic.com/legal/aup).
1304* **Inappropriate content:** Claude does not process inappropriate or explicit images that violate the [Usage Policy](https://www.anthropic.com/legal/aup).
13051305* **Healthcare applications:** Although Claude can analyze general medical images, it is not designed to interpret complex diagnostic scans such as CTs or MRIs. Claude's outputs should not be considered a substitute for professional medical advice or diagnosis.
13061306
13071307Always carefully review and verify Claude's image interpretations, especially for high-stakes use cases. Do not use Claude for tasks requiring perfect precision or sensitive image analysis without human oversight.
from line 1324
13241324 </Accordion>
13251325
13261326 <Accordion title="How many images can I include in one request?">
1327 Up to 600 per API request (100 for models with a 200k-token context window) and 20 per turn on claude.ai. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for details and the lower per-image dimension limit that applies above 20 images.
1327 Up to 600 for each API request (100 for models with a 200k-token context window) and 20 for each turn on claude.ai. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for details and the lower per-image dimension limit that applies above 20 images.
13281328 </Accordion>
13291329
13301330 <Accordion title="Does Claude read image metadata?">
from line 1335
13351335 No. Image uploads are ephemeral and not stored beyond the duration of the API request. Uploaded images are automatically deleted after they have been processed.
13361336 </Accordion>
13371337
1338 <Accordion title="Where can I find details on data privacy for image uploads?">
1338 <Accordion title="Where are the details on data privacy for image uploads?">
13391339 Refer to the Anthropic privacy policy page for information on how uploaded images and other data are handled. Anthropic does not use uploaded images to train models.
13401340 </Accordion>
13411341
from line 1359
13591359## Next steps
13601360
13611361<CardGroup cols={2}>
1362 <Card title="Multimodal cookbook" icon="image" href="https://platform.claude.com/cookbook/multimodal-getting-started-with-vision">
1362 <Card title="Multimodal recipe" icon="image" href="https://platform.claude.com/cookbook/multimodal-getting-started-with-vision">
13631363 Get tips and best-practice techniques for tasks such as interpreting charts and extracting content from forms.
13641364 </Card>
13651365
build-with-claude/vision-coordinates Changed · +9 / -9 lines
from line 9
99You'll need this for OCR pipelines, form extraction, chart parsing, UI element location, and any task where you act on a specific region of an image. For sending images, supported formats, and per-model resolution limits, see [Vision](https://platform.claude.com/docs/en/build-with-claude/vision).
1010
1111<Note>
12 **Claude works best with absolute pixel coordinates.** Ask for them explicitly in your prompt. For example: *"Return the bounding box of each table as `[x1, y1, x2, y2]` (top-left and bottom-right corners) in pixel coordinates."* Claude does not work well when you ask for normalized coordinates, for example: *"Return bounding box coordinates between `0` and `1000`."* Always ask for pixel coordinates and normalize in your own code if you need to. To get coordinates as machine-readable JSON instead of prose, define a schema with [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), for example an object with an `[x1, y1, x2, y2]` array per detected element.
12 **Claude works best with absolute pixel coordinates.** Ask for them explicitly in your prompt. For example: *"Return the bounding box of each table as `[x1, y1, x2, y2]` (top-left and bottom-right corners) in pixel coordinates."* Claude does not work well when you ask for normalized coordinates, for example: *"Return bounding box coordinates between `0` and `1000`."* Always ask for pixel coordinates and normalize in your own code if you need to. To get coordinates as machine-readable JSON instead of prose, define a schema with [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), for example an object with an `[x1, y1, x2, y2]` array for each detected element.
1313</Note>
1414
15Coordinates follow the standard image convention: the origin `(0, 0)` is the top-left corner of the image, with x increasing to the right and y increasing downward. The coordinates Claude returns are pixel positions in the image Claude sees: your image after Claude resizes it to fit the model's native resolution (see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)). To get coordinates you can use directly, either pre-resize your image so the coordinates map one-to-one onto the image you have (see [Resize your image before uploading](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#resize-your-image-before-uploading)), or rescale the coordinates Claude returns (see [Rescale coordinates when you cannot pre-resize](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#rescale-coordinates-when-you-cannot-pre-resize)).
15Coordinates follow the standard image convention: the origin `(0, 0)` is the top-left corner of the image, with x increasing to the right and y increasing downward. The coordinates Claude returns are pixel positions in the image Claude processes: your image after Claude resizes it to fit the model's native resolution (see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)). To get coordinates you can use directly, either pre-resize your image so the coordinates map one-to-one onto the image you have (see [Resize your image before uploading](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#resize-your-image-before-uploading)), or rescale the coordinates Claude returns (see [Rescale coordinates when you cannot pre-resize](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#rescale-coordinates-when-you-cannot-pre-resize)).
1616
1717<Note>
1818 Claude's spatial reasoning has limits (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/vision#limitations)). Coordinate accuracy is best when you state the expected coordinate format in your prompt and spot-check results visually before processing at scale. Small elements lose precision when an image is downscaled: for fine targets, crop the region of interest and send the crop (offset returned coordinates by the crop origin), or use a high-resolution-tier model. For [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support), pages are rasterized to images server-side at dimensions you don't control, so the returned coordinates can't be reliably mapped back onto the page. To work with coordinates on PDF content, rasterize the pages to images yourself and use the pre-resize approach.
from line 39
3939
4040## Resize your image before uploading
4141
42The most reliable approach is to resize your image yourself before uploading, so the image you have is exactly the image Claude sees and the coordinates Claude returns need no conversion.
42The most reliable approach is to resize your image yourself before uploading, so the image you have is exactly the image Claude processes and the coordinates Claude returns need no conversion.
4343
4444First check which resolution tier your model is on (see [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size)) and pass the matching edge and token limits. The following reference implementation computes the exact size Claude resizes an image to:
4545
from line 457
457457}
458458```
459459
460A request whose marked image (any block that sets `"oversized_image": "error"`) would be resized is rejected with a 400 `invalid_request_error` naming the image's dimensions and the largest dimensions that fit. Whether an image triggers the rejection depends on the [limits of every model the request names](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images): the 1920×1080 example below is rejected by a standard-tier model but fits within the high-resolution tier:
460A request whose marked image (any block that sets `"oversized_image": "error"`) would be resized is rejected with a 400 `invalid_request_error` naming the image's dimensions and the largest dimensions that fit. Whether an image triggers the rejection depends on the [limits of every model the request names](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images): the following 1920×1080 example is rejected by a standard-tier model but fits within the high-resolution tier:
461461
462462```text wrap
463463messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"
from line 465
465465
466466Rescale to the reported target and resend: the target is the largest size, at your image's aspect ratio, that every model named on the request accepts. How marked images interact with the [server-side fallback beta](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) is described with that feature; in every mode, a marked image is never served resized.
467467
468The setting is per image. `"oversized_image": "downsize"` (the default when the field is omitted) keeps automatic resizing as described on this page. Each image block is checked only against its own setting, so one request can mix images whose dimensions are load-bearing (a screenshot you'll click on) with images where resizing is harmless (a logo). What the setting does and does not change:
468Each image has its own setting. `"oversized_image": "downsize"` (the default when the field is omitted) keeps automatic resizing as described on this page. Each image block is checked only against its own setting, so one request can mix images whose dimensions matter (a screenshot you'll click) with images where resizing is harmless (a logo). What the setting does and does not change:
469469
470* Padding ([which never discards content](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)), format conversion, and orientation correction proceed as usual.
470* [Padding](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images) (which never discards content), format conversion, and orientation correction proceed as usual.
471471* The hard limits (8000 px on the longest side, and the stricter per-image limit on [many-image requests](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)) are separate rejections; this setting never lets an image past them.
472472* Images supplied by URL or file ID are checked once their bytes have been fetched; those rejections carry the same message without the leading position, so they don't identify which image failed; only embedded base64 images are named by position in the error.
473473* [PDF pages](https://platform.claude.com/docs/en/build-with-claude/pdf-support) are rasterized server-side at dimensions you don't control; the `document` block does not accept the field (an image block nested inside a document's content accepts it like any other).
474* A marked image whose dimensions cannot be determined is rejected rather than passed through: that rejection reports that the image's source dimensions could not be determined, not the resize message quoted above. No image that sets `"error"` reaches the model resized.
474* A marked image whose dimensions cannot be determined is rejected rather than passed through: that rejection reports that the image's source dimensions could not be determined, not the resize message quoted earlier. No image that sets `"error"` reaches the model resized.
475475
476476The [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) endpoint honors `transformations` too, rejecting an embedded image exactly as the Messages API would, so you can check whether an embedded image fits without being resized, before running inference. Counting rejects images supplied by URL or file ID rather than fetching them, so a marked image from those sources is checked only at Messages time.
477477
478478## Rescale coordinates when you cannot pre-resize
479479
480If you cannot pre-resize (for example, when the image comes from an upstream system you can't modify), use the resize helper from [Resize your image before uploading](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#resize-your-image-before-uploading) to recover the dimensions Claude saw, then map the coordinates Claude returns into normalized coordinates or back onto your original image. Unless an image [opts into an error instead](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error), Claude resizes oversized images rather than rejecting them, up to the API's [request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits). Beyond those limits the request fails with a validation error instead. Pass the tier limits that match the model you called: the wrong tier's limits recover the wrong resized dimensions and silently shift every coordinate. This approach requires knowing the pixel dimensions of the image you uploaded, so it does not apply to PDF uploads.
480If you cannot pre-resize (for example, when the image comes from an upstream system you can't modify), use the resize helper from [Resize your image before uploading](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#resize-your-image-before-uploading) to recover the dimensions of the image Claude processed, then map the coordinates Claude returns into normalized coordinates or back onto your original image. Unless an image opts into an [oversized-image error](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error) instead, Claude resizes oversized images rather than rejecting them, up to the API's [request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits). Beyond those limits the request fails with a validation error instead. Pass the tier limits that match the model you called: the wrong tier's limits recover the wrong resized dimensions and silently shift every coordinate. This approach requires knowing the pixel dimensions of the image you uploaded, so it does not apply to PDF uploads.
481481
482482Screenshots and zoom images that you return to the [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) toolsets are an exception to automatic resizing. The API rejects a `tool_result` image that exceeds the model's limits with a validation error instead of resizing it. Resize those images in your application before returning them, then scale the coordinates Claude returns back to your screen's dimensions.
483483
build-with-claude/working-with-messages Changed · +6 / -6 lines
from line 20
2020## Basic request and response
2121
2222<Note>
23 The `temperature`, `top_p`, and `top_k` sampling parameters are not supported on Claude 4.7 and later models and Claude Mythos Preview, or on any model starting with [API version `2026-10-21`](https://platform.claude.com/docs/en/api/migration-2026-10-21#sampling-parameters). Setting them to a non-default value returns a 400 error, and starting with `2026-10-21` any value does. Omit them from request payloads and use prompting to guide the model's behavior instead. See the [migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes).
23 The `temperature`, `top_p`, and `top_k` sampling parameters are not supported on Claude 4.7 and later models and Claude Mythos Preview, or on any model starting with [API version `2026-10-21`](https://platform.claude.com/docs/en/api/migration-2026-10-21#sampling-parameters). Setting them to a non-default value returns a 400 error, and starting with `2026-10-21` any value does. Omit them from request payloads and use prompting to guide the model's behavior instead. See the [breaking changes in the migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes).
2424</Note>
2525
2626<CodeGroup>
from line 123
123123 client = Anthropic::Client.new
124124
125125 message = client.messages.create(
126 model: "claude-opus-5-5",
126 model: Anthropic::Model::CLAUDE_OPUS_5_5,
127127 max_tokens: 1024,
128128 messages: [
129129 { role: "user", content: "Hello, Claude" }
from line 288
288288 client = Anthropic::Client.new
289289
290290 message = client.messages.create(
291 model: "claude-opus-5-5",
291 model: Anthropic::Model::CLAUDE_OPUS_5_5,
292292 max_tokens: 1024,
293293 messages: [
294294 { role: "user", content: "Hello, Claude" },
from line 331
331331
332332## Prefilling Claude's response
333333
334You can pre-fill part of Claude's response in the last position of the input messages list. Use this technique to shape Claude's response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
334You can prefill part of Claude's response in the last position of the input messages list. Use this technique to shape Claude's response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
335335
336336<Warning>
337337 Prefilling is not supported on Claude 4.6 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). Requests using prefill with these models return a 400 error. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) on models that support it, or system prompt instructions, instead. See the [migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide) for migration patterns.
from line 464
464464 client = Anthropic::Client.new
465465
466466 message = client.messages.create(
467 model: "claude-sonnet-4-5",
467 model: Anthropic::Model::CLAUDE_SONNET_4_5,
468468 max_tokens: 1,
469469 messages: [
470470 {
from line 501
501501
502502## Vision
503503
504Claude can read both text and images in requests. You can supply images using the `base64`, `url`, or `file` source types. The `file` source type references an image uploaded through the [Files API](https://platform.claude.com/docs/en/build-with-claude/files). Supported media types are `image/jpeg`, `image/png`, `image/gif`, and `image/webp`. See the [vision guide](https://platform.claude.com/docs/en/build-with-claude/vision) for more details.
504Claude can read both text and images in requests. You can supply images using the `base64`, `url`, or `file` source types. The `file` source type references an image uploaded through the [Files API](https://platform.claude.com/docs/en/build-with-claude/files). Supported media types are `image/jpeg`, `image/png`, `image/gif`, and `image/webp`. See the [Vision](https://platform.claude.com/docs/en/build-with-claude/vision) guide for more details.
505505
506506<CodeGroup>
507507 ```bash cURL
claude_api_primer Changed · +12 / -12 lines
from line 386
386386
387387### Interleaved thinking
388388
389Interleaved thinking enables Claude to think between tool calls, reasoning about tool results before determining the next step.
389Interleaved thinking allows Claude to think between tool calls, reasoning about tool results before determining the next step.
390390
391391<Info>
392392 On models with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {type: "adaptive"}`), interleaved thinking is automatically enabled. No beta header is needed. Sonnet 4.6 supports both the `interleaved-thinking-2025-05-14` beta header with manual extended thinking and adaptive thinking.
from line 494
494494
495495Client tools are specified in the `tools` top-level parameter of the API request. Each tool definition includes:
496496
497| Parameter | Description |
498| -------------- | --------------------------------------------------------------------------------------------------- |
499| `name` | The name of the tool. Must match the regex `^[a-zA-Z0-9_-]{1,128}$`. |
500| `description` | A detailed plaintext description of what the tool does, when it should be used, and how it behaves. |
501| `input_schema` | A [JSON Schema](https://json-schema.org/) object defining the expected parameters for the tool. |
497| Parameter | Description |
498| -------------- | ---------------------------------------------------------------------------------------------------- |
499| `name` | The name of the tool. Must match the regex `^[a-zA-Z0-9_-]{1,128}$`. |
500| `description` | A detailed plain text description of what the tool does, when it should be used, and how it behaves. |
501| `input_schema` | A [JSON Schema](https://json-schema.org/) object defining the expected parameters for the tool. |
502502
503503```json
504504{
from line 564
564564
565565When working with the `tool_choice` parameter, there are four possible options:
566566
567* `auto` allows Claude to determine whether to call any provided tools or not (default).
567* `auto` allows Claude to determine whether to call any provided tools (default).
568568* `any` tells Claude that it must use one of the provided tools.
569569* `tool` forces Claude to always use a particular tool.
570570* `none` prevents Claude from using any tools.
from line 577
577577
578578### Parallel tool use
579579
580By default, Claude may use multiple tools to answer a user query. You can disable this behavior by setting `disable_parallel_tool_use=true`.
580By default, Claude might use multiple tools to answer a user query. You can disable this behavior by setting `disable_parallel_tool_use=true`.
581581
582582## Handling tool use and tool result content blocks
583583
from line 585
585585
586586The response has a `stop_reason` of `tool_use` and one or more `tool_use` content blocks that include:
587587
588* `id`: A unique identifier for this particular tool use block.
589* `name`: The name of the tool being used.
590* `input`: An object containing the input being passed to the tool.
588* `id`: A unique identifier for this particular tool use block
589* `name`: The name of the tool being used
590* `input`: An object containing the input being passed to the tool
591591
592592```json
593593{
from line 628
628628
629629### Handling the `pause_turn` stop reason
630630
631When using server tools such as web search, the API may return a `pause_turn` stop reason. Continue the conversation by passing the paused response back as-is in a subsequent request.
631When using server tools such as web search, the API might return a `pause_turn` stop reason. Continue the conversation by passing the paused response back as-is in a subsequent request.
632632
633633## Troubleshooting errors
634634
cli-sdks-libraries/cli/authentication Changed · +4 / -4 lines
from line 4
44description: Authenticate the ant CLI with interactive login, API keys, named profiles, and Workload Identity Federation.
55---
66
7The `ant` CLI supports several credential sources. The [Quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart#authentication) covers the one-command happy path (`ant auth login`). This page covers every option in full.
7The `ant` CLI supports several credential sources. The [Quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart#authentication) covers the one-command login (`ant auth login`). This page covers every option in full.
88
99## Interactive login
1010
from line 71
7171 </Tab>
7272</Tabs>
7373
74To override the key for a single invocation, pass [`--api-key-stdin`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#global-flags) and pipe the key to the command. To point at a different API host, set `ANTHROPIC_BASE_URL` or pass `--base-url`.
74To override the key for a single run, pass [`--api-key-stdin`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#global-flags) and pipe the key to the command. To point at a different API host, set `ANTHROPIC_BASE_URL` or pass `--base-url`.
7575
76If you are using an API key scoped to multiple workspaces, such as a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types), you must [specify the workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) to run your command in. Do this by setting an `ANTHROPIC_WORKSPACE_ID` environment variable, which the CLI reads automatically, or by using the [`--workspace-id` flag](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#global-flags). The value must be a `wrkspc_...` ID.
76If you are using a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, you must [specify the workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) to run your command in. Do this by setting an `ANTHROPIC_WORKSPACE_ID` environment variable, which the CLI reads automatically, or by using the [`--workspace-id` flag](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#global-flags). The value must be a `wrkspc_...` ID.
7777
7878```bash CLI
7979ant messages create \
from line 152
152152 </Card>
153153
154154 <Card title="CLI scripting and automation" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting">
155 Version-control API resources, scripting patterns, and use from Claude Code
155 Version control for API resources, scripting patterns, and use from Claude Code
156156 </Card>
157157
158158 <Card title="Workload Identity Federation" icon="cloud" href="https://platform.claude.com/docs/en/manage-claude/workload-identity-federation">
cli-sdks-libraries/cli/using Changed · +16 / -16 lines
from line 27
2727
2828### Global flags
2929
30| Flag | Description |
31| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
32| `--profile` | Named profile to use for this invocation (equivalent to setting `ANTHROPIC_PROFILE`). See [Switch between workspaces](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication#switch-between-workspaces). |
33| `--api-key-stdin` | Read the API key from standard input. The flag reads all of standard input, so pass the request body with [flags](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#flags). |
34| `--auth-token-stdin` | Read the bearer token from standard input. The flag reads all of standard input, so pass the request body with [flags](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#flags). |
35| `--format` | Output format: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` |
36| `--transform` | Filter or reshape the response with a [GJSON path](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#transform-output-with-gjson) |
37| `-r`, `--raw-output` | Print string results without surrounding quotes, like `jq -r` |
38| `--base-url` | Override the API base URL |
39| `--workspace-id` | Optional. Workspace ID (`wrkspc_...`) to send as the `anthropic-workspace-id` header, for API keys with access to multiple workspaces (equivalent to setting `ANTHROPIC_WORKSPACE_ID`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) commands take their own `--workspace-id`, which names the workspace they manage instead. |
40| `--debug` | Print full HTTP request and response to stderr |
41| `--format-error`, `--transform-error` | Same as `--format` and `--transform` but applied to [error responses](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting#inspect-errors) |
30| Flag | Description |
31| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32| `--profile` | Named profile to use for this command (equivalent to setting `ANTHROPIC_PROFILE`). See [Switch between workspaces](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication#switch-between-workspaces). |
33| `--api-key-stdin` | Read the API key from standard input. The flag reads all of standard input, so pass the request body with [flags](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#flags). |
34| `--auth-token-stdin` | Read the bearer token from standard input. The flag reads all of standard input, so pass the request body with [flags](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#flags). |
35| `--format` | Output format: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` |
36| `--transform` | Filter or reshape the response with a GJSON path. See [Transform output with GJSON](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#transform-output-with-gjson). |
37| `-r`, `--raw-output` | Print string results without surrounding quotes, like `jq -r` |
38| `--base-url` | Override the API base URL |
39| `--workspace-id` | Optional. Workspace ID (`wrkspc_...`) to send as the `anthropic-workspace-id` header, for API keys that aren't scoped to a workspace (equivalent to setting `ANTHROPIC_WORKSPACE_ID`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) commands take their own `--workspace-id`, which names the workspace they manage instead. |
40| `--debug` | Print full HTTP request and response to stderr |
41| `--format-error`, `--transform-error` | Same as `--format` and `--transform` but applied to [error responses](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting#inspect-errors) |
4242
4343## Output formats
4444
from line 56
5656...
5757```
5858
59List endpoints auto-paginate. In the default formats each item is written separately (one compact JSON object per line in `jsonl` mode, a stream of YAML documents in `yaml` mode), which streams cleanly into `head`, `grep`, and `--transform` filters.
59List endpoints auto-paginate. In the default formats each item is written separately (one compact JSON object on each line in `jsonl` mode, a stream of YAML documents in `yaml` mode), which streams cleanly into `head`, `grep`, and `--transform` filters.
6060
6161### Interactive explorer
6262
63The explorer is a fold-and-search TUI for browsing large responses. Arrow keys expand and collapse nodes, `/` searches, `q` exits. List and retrieve commands open it by default when connected to a terminal. Pass `--format explore` to open it explicitly:
63The explorer is a fold-and-search TUI for browsing large responses. Arrow keys expand and collapse nodes, `/` searches, and `q` exits. List and retrieve commands open it by default when connected to a terminal. Pass `--format explore` to open it explicitly:
6464
6565```bash
6666ant models list --format explore
from line 193
193193
194194## Available resources
195195
196Every API resource the CLI exposes is documented in the [API reference](https://platform.claude.com/docs/en/api/cli/messages/create). For a local listing, run `ant --help`, and append `--help` to any subcommand for its flags and parameters.
196Every API resource the CLI exposes is documented in the [API reference](https://platform.claude.com/docs/en/api/cli/messages/create). For a local list, run `ant --help`, and append `--help` to any subcommand for its flags and parameters.
197197
198198## Next steps
199199
200200<CardGroup cols={3}>
201201 <Card title="CLI scripting and automation" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting">
202 Version-control API resources, scripting patterns, and use from Claude Code
202 Version control for API resources, scripting patterns, and use from Claude Code
203203 </Card>
204204
205205 <Card title="API reference" icon="book" href="https://platform.claude.com/docs/en/api/cli/messages/create">
cli-sdks-libraries/libraries/apple-foundation-models Changed · +4 / -4 lines
from line 6
66
77[Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) is a Swift package that makes Claude available as a server-side language model in Apple's [Foundation Models](https://developer.apple.com/documentation/foundationmodels) framework. The package conforms Claude to the framework's `LanguageModel` protocol, so you drive it with the same `LanguageModelSession` API you use for Apple's on-device model: `respond(to:)`, streaming, guided generation, and tool calling all work the same way.
88
9Requests go directly from your app to the Claude API; Apple is not in the request path and does not see prompts or responses. Usage is billed to your Anthropic account at [standard API pricing](https://platform.claude.com/docs/en/about-claude/pricing), so your organization needs an available credit balance or an active billing method. Your app decides when to use Claude and when to use Apple's on-device model: pass whichever model you want to each session.
9Requests go directly from your app to the Claude API; Apple is not in the request path and does not see prompts or responses. Usage is billed to your Anthropic account at [standard API pricing](https://platform.claude.com/docs/en/about-claude/pricing), so your organization needs an available credit balance or an active billing method. Your app determines when to use Claude and when to use Apple's on-device model: pass whichever model you want to each session.
1010
1111<Note>
1212 **Beta.** This package targets the Foundation Models server-side language model API introduced in the OS 27 betas. APIs might change during the beta.
from line 131
131131
132132The first time your app uses Claude on a device, the app requests a challenge from Anthropic, attests the device with Apple's `DCAppAttestService`, and exchanges the verified attestation for an access token. The Claude for Foundation Models package runs this flow automatically and requests new tokens as they expire; there is no attestation code for you to write.
133133
134Tokens are scoped to your workspace, expire after one hour, and authorize only [Messages API](https://platform.claude.com/docs/en/api/messages/create) calls. They carry no end-user identity: App Attest identifies your app, not the person using it, so handle any per-user logic in your app.
134Tokens are scoped to your workspace, expire after 1 hour, and authorize only [Messages API](https://platform.claude.com/docs/en/api/messages/create) calls. They carry no end-user identity: App Attest identifies your app, not the person using it, so handle any per-user logic in your app.
135135
136136To stop a compromised or retired app, revoke its integration. In the Claude Console, go to the [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) page (`platform.claude.com/settings/workspaces/default/app-integrations`). Each app integration belongs to one workspace. In the workspace picker in the sidebar, select the workspace that holds the integration. Select the integration and click **Revoke**, then confirm. Revoking an integration revokes its outstanding tokens, and its registered devices can no longer request new ones. Revocation is permanent, so create a new app integration to restore access.
137137
from line 193
193193
194194### Client-side tools
195195
196The framework's `tools:` array works unchanged. Conform your types to `Tool`, pass them to `LanguageModelSession`, and the framework invokes them on the device when Claude calls them. See [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).
196The framework's `tools:` array works unchanged. Conform your types to `Tool`, pass them to `LanguageModelSession`, and the framework runs them on the device when Claude calls them. See [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).
197197
198198```swift
199199let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])
from line 201
201201
202202### Server-side tools
203203
204[Server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) (web search, web fetch, and code execution) run on Anthropic's infrastructure within a single round trip, with nothing for the framework to invoke on the device. Configure them for each model with `serverTools:`:
204[Server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) (web search, web fetch, and code execution) run on Anthropic's infrastructure within a single round trip, with nothing for the framework to call on the device. Configure them for each model with `serverTools:`:
205205
206206```swift
207207let model = ClaudeLanguageModel(
cli-sdks-libraries/libraries/openai-sdk Changed · +55 / -55 lines
from line 1
11---
22title: OpenAI SDK compatibility
33url: https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk
4description: Anthropic provides a compatibility layer that enables you to use the OpenAI SDK to test the Claude API. With a few code changes, you can quickly evaluate Anthropic model capabilities.
4description: Anthropic provides a compatibility layer that lets you use the OpenAI SDK to test the Claude API. With a few code changes, you can quickly evaluate Anthropic model capabilities.
55---
66
77<Note>
8 This compatibility layer is primarily intended to test and compare model capabilities, and is not considered a long-term or production-ready solution for most use cases. While it is intended to remain fully functional and not have breaking changes, the priority is the reliability and effectiveness of the [Claude API](https://platform.claude.com/docs/en/api/overview).
8 This compatibility layer is primarily intended to test and compare model capabilities, and is not considered a long-term or production-ready solution for most use cases. Although it is intended to remain fully functional and not have breaking changes, the priority is the reliability and effectiveness of the [Claude API](https://platform.claude.com/docs/en/api/overview).
99
1010 For more information on known compatibility limitations, see [Important OpenAI compatibility limitations](https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk#important-openai-compatibility-limitations).
1111
12 If you encounter any issues with the OpenAI SDK compatibility feature, please share your feedback via this [compatibility feedback form](https://forms.gle/oQV4McQNiuuNbz9n8).
12 If you encounter any issues with the OpenAI SDK compatibility feature, share your feedback through this [compatibility feedback form](https://forms.gle/oQV4McQNiuuNbz9n8).
1313</Note>
1414
1515<Tip>
16 For the best experience and access to Claude API full feature set ([PDF processing](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [citations](https://platform.claude.com/docs/en/build-with-claude/citations), [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), and [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)), use the native [Claude API](https://platform.claude.com/docs/en/api/overview).
16 For the best experience and access to the full Claude API feature set ([PDF processing](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [citations](https://platform.claude.com/docs/en/build-with-claude/citations), [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), and [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)), use the native [Claude API](https://platform.claude.com/docs/en/api/overview).
1717</Tip>
1818
1919## Getting started with the OpenAI SDK
from line 20
2020
2121To use the OpenAI SDK compatibility feature, you'll need to:
2222
231. Use an official OpenAI SDK
231. Use an official OpenAI SDK.
2424
25252. Change the following
2626
2727 * Update your base URL to point to the Claude API
2828 * Replace your API key with a [Claude API key](https://platform.claude.com/settings/keys) from the Claude Console
29 * If your key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, also send the `anthropic-workspace-id` header on every request (for example, `default_headers` in the Python SDK or `defaultHeaders` in TypeScript); see [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace)
29 * If your key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, also send the `anthropic-workspace-id` header on every request (for example, `default_headers` in the Python SDK or `defaultHeaders` in TypeScript); see [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace)
3030 * Update your model name to use a [Claude model](https://platform.claude.com/docs/en/models/overview)
3131
323. Review the following sections for what features are supported
323. Review the following sections for what features are supported.
3333
3434### Quick start example
3535
from line 184
184184Here are the most substantial differences from using OpenAI:
185185
186186* The `strict` parameter for function calling is ignored, which means the tool use JSON is not guaranteed to follow the supplied schema. For guaranteed schema conformance, use the native [Claude API with Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
187* Audio input is not supported; it will be ignored and stripped from input
188* Prompt caching is not supported, but it is supported in the [Anthropic SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview)
187* Audio input is not supported; it is ignored and stripped from input.
188* Prompt caching is not supported, but it is supported in the [Anthropic SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview).
189189* System/developer messages are hoisted and concatenated into the top-level `system` field, wherever they appear in the conversation. To add system instructions partway through a conversation, use [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) in the native Claude API.
190190
191191Most unsupported fields are silently ignored rather than producing errors. These are all documented in the following sections.
from line 192
192192
193193### Output quality considerations
194194
195If you’ve done lots of tweaking to your prompt, it’s likely to be well-tuned to OpenAI specifically. Consider reworking it for Claude using the [prompting best practices guide](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).
195If you’ve adjusted your prompt extensively, it’s likely to be well-tuned to OpenAI specifically. Consider reworking it for Claude using the [prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) guide.
196196
197197### System / developer message hoisting
198198
199Most of the inputs to the OpenAI SDK clearly map directly to Anthropic’s API parameters, but one distinct difference is the handling of system / developer prompts. These two prompts can be put throughout a chat conversation via OpenAI. The compatibility layer takes all system/developer messages and concatenates them together with a single newline (`\n`) in between them. This full string is then supplied as the top-level `system` field, ahead of every message.
199Most of the inputs to the OpenAI SDK clearly map directly to Claude API parameters, but one distinct difference is the handling of system / developer prompts. These two prompts can be put throughout a chat conversation in the OpenAI API. The compatibility layer takes all system/developer messages and concatenates them together with a single newline (`\n`) in between them. This full string is then supplied as the top-level `system` field, ahead of every message.
200200
201201### Thinking support
202202
from line 297
297297| `n` | Must be exactly 1 |
298298| `logprobs` | Ignored |
299299| `metadata` | Ignored |
300| `response_format` | Ignored. For JSON output, use [Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API |
300| `response_format` | Ignored. For JSON output, use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API |
301301| `prediction` | Ignored |
302302| `presence_penalty` | Ignored |
303303| `frequency_penalty` | Ignored |
from line 318
318318 <Tab title="Tools">
319319 `tools[n].function` fields
320320
321 | Field | Support status |
322 | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
323 | `name` | Fully supported |
324 | `description` | Fully supported |
325 | `parameters` | Fully supported |
326 | `strict` | Ignored. Use [Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with native Claude API for strict schema validation |
321 | Field | Support status |
322 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
323 | `name` | Fully supported |
324 | `description` | Fully supported |
325 | `parameters` | Fully supported |
326 | `strict` | Ignored. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API for strict schema validation |
327327 </Tab>
328328
329329 <Tab title="Functions">
from line 330
330330 `functions[n]` fields
331331
332332 <Info>
333 OpenAI has deprecated the `functions` field and suggests using `tools` instead.
333 OpenAI has deprecated the `functions` field and recommends using `tools` instead.
334334 </Info>
335335
336 | Field | Support status |
337 | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
338 | `name` | Fully supported |
339 | `description` | Fully supported |
340 | `parameters` | Fully supported |
341 | `strict` | Ignored. Use [Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with native Claude API for strict schema validation |
336 | Field | Support status |
337 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
338 | `name` | Fully supported |
339 | `description` | Fully supported |
340 | `parameters` | Fully supported |
341 | `strict` | Ignored. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API for strict schema validation |
342342 </Tab>
343343 </Tabs>
344344</Accordion>
from line 351
351351 Fields for `messages[n].role == "developer"`
352352
353353 <Info>
354 Developer messages are hoisted to beginning of conversation as part of the initial system message
354 Developer messages are hoisted to the beginning of the conversation as part of the initial system message.
355355 </Info>
356356
357357 | Field | Support status |
from line 364
364364 Fields for `messages[n].role == "system"`
365365
366366 <Info>
367 System messages are hoisted to beginning of conversation as part of the initial system message
367 System messages are hoisted to the beginning of the conversation as part of the initial system message.
368368 </Info>
369369
370370 | Field | Support status |
from line 428
428428
429429### Response fields
430430
431| Field | Support status |
432| --------------------------------- | ------------------------------ |
433| `id` | Fully supported |
434| `choices[]` | Will always have a length of 1 |
435| `choices[].finish_reason` | Fully supported |
436| `choices[].index` | Fully supported |
437| `choices[].message.role` | Fully supported |
438| `choices[].message.content` | Fully supported |
439| `choices[].message.tool_calls` | Fully supported |
440| `object` | Fully supported |
441| `created` | Fully supported |
442| `model` | Fully supported |
443| `finish_reason` | Fully supported |
444| `content` | Fully supported |
445| `usage.completion_tokens` | Fully supported |
446| `usage.prompt_tokens` | Fully supported |
447| `usage.total_tokens` | Fully supported |
448| `usage.completion_tokens_details` | Always empty |
449| `usage.prompt_tokens_details` | Always empty |
450| `choices[].message.refusal` | Always empty |
451| `choices[].message.audio` | Always empty |
452| `logprobs` | Always empty |
453| `service_tier` | Always empty |
454| `system_fingerprint` | Always empty |
431| Field | Support status |
432| --------------------------------- | ------------------------ |
433| `id` | Fully supported |
434| `choices[]` | Always has a length of 1 |
435| `choices[].finish_reason` | Fully supported |
436| `choices[].index` | Fully supported |
437| `choices[].message.role` | Fully supported |
438| `choices[].message.content` | Fully supported |
439| `choices[].message.tool_calls` | Fully supported |
440| `object` | Fully supported |
441| `created` | Fully supported |
442| `model` | Fully supported |
443| `finish_reason` | Fully supported |
444| `content` | Fully supported |
445| `usage.completion_tokens` | Fully supported |
446| `usage.prompt_tokens` | Fully supported |
447| `usage.total_tokens` | Fully supported |
448| `usage.completion_tokens_details` | Always empty |
449| `usage.prompt_tokens_details` | Always empty |
450| `choices[].message.refusal` | Always empty |
451| `choices[].message.audio` | Always empty |
452| `logprobs` | Always empty |
453| `service_tier` | Always empty |
454| `system_fingerprint` | Always empty |
455455
456456### Error message compatibility
457457
458The compatibility layer maintains consistent error formats with the OpenAI API. However, the detailed error messages will not be equivalent. Only use the error messages for logging and debugging.
458The compatibility layer maintains consistent error formats with the OpenAI API. However, the detailed error messages are not equivalent. Only use the error messages for logging and debugging.
459459
460460### Header compatibility
461461
462While the OpenAI SDK automatically manages headers, here is the complete list of headers supported by the Claude API for developers who need to work with them directly.
462Although the OpenAI SDK automatically manages headers, here is the complete list of headers supported by the Claude API for developers who need to work with them directly.
463463
464| Header | Support Status |
464| Header | Support status |
465465| -------------------------------- | ------------------- |
466466| `x-ratelimit-limit-requests` | Fully supported |
467467| `x-ratelimit-limit-tokens` | Fully supported |
cli-sdks-libraries/sdks/csharp Changed · +8 / -8 lines
from line 53
5353}
5454```
5555
56For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
56For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
5757
5858## Client configuration
5959
from line 104
104104Console.WriteLine(message);
105105```
106106
107Using a [`with` expression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) makes it easy to construct the modified options.
107You can use a [`with` expression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) to construct the modified options.
108108
109109The `WithOptions` method does not affect the original client or service.
110110
from line 152
152152
153153Additionally, all 4xx errors inherit from `Anthropic4xxException`.
154154
155* `AnthropicSseException`: thrown for errors encountered during SSE streaming after a successful initial HTTP response.
155* `AnthropicSseException`: Errors encountered during SSE streaming after a successful initial HTTP response.
156156
157157* `AnthropicIOException`: I/O networking errors.
158158
from line 172
172172* 429 Rate Limit
173173* 5xx Internal
174174
175The API may also explicitly instruct the SDK to retry or not retry a request.
175The API might also explicitly instruct the SDK to retry or not retry a request.
176176
177177To set a custom number of retries, configure the client using the `MaxRetries` property:
178178
from line 263
263263
264264## Response validation
265265
266In rare cases, the API may return a response that doesn't match the expected type. By default, the SDK does not throw an exception in this case. It throws `AnthropicInvalidDataException` only if you directly access the property.
266In rare cases, the API might return a response that doesn't match the expected type. By default, the SDK does not throw an exception in this case. It throws `AnthropicInvalidDataException` only if you directly access the property.
267267
268268If you would prefer to check that the response is completely well-typed upfront, then either call `Validate`:
269269
from line 296
296296
297297## IChatClient integration
298298
299The SDK provides an implementation of the `IChatClient` interface from the `Microsoft.Extensions.AI.Abstractions` library. This enables `AnthropicClient` (and `Anthropic.Services.IBetaService`) to be used with other libraries that integrate with these core abstractions. For example, tools in the MCP C# SDK (`ModelContextProtocol`) library can be used directly with an `AnthropicClient` exposed through `IChatClient`.
299The SDK provides an implementation of the `IChatClient` interface from the `Microsoft.Extensions.AI.Abstractions` library. This allows `AnthropicClient` (and `Anthropic.Services.IBetaService`) to be used with other libraries that integrate with these core abstractions. For example, tools in the MCP C# SDK (`ModelContextProtocol`) library can be used directly with an `AnthropicClient` exposed through `IChatClient`.
300300
301301```csharp
302302using Anthropic;
from line 324
324324
325325To send a request to the Claude API, build an instance of a `Params` class and pass it to the corresponding client method. When the response is received, it's deserialized into an instance of a C# class.
326326
327For example, `client.Messages.Create` should be called with an instance of `MessageCreateParams`, and it will return an instance of `Task<Message>`.
327For example, `client.Messages.Create` should be called with an instance of `MessageCreateParams`, and it returns an instance of `Task<Message>`.
328328
329329## Advanced usage
330330
331331### Binary responses
332332
333The SDK defines methods that return binary responses, which are used for API responses that shouldn't necessarily be parsed, like non-JSON data.
333The SDK defines methods that return binary responses, which are used for API responses that shouldn't necessarily be parsed, such as non-JSON data.
334334
335335These methods return `HttpResponse`:
336336
cli-sdks-libraries/sdks/go Changed · +21 / -21 lines
### Deserializing parameters #### Undocumented request parameters ### Deserializing params #### Undocumented request params
from line 63
6363}
6464```
6565
66For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
66For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
6767
6868<AccordionGroup>
6969 <Accordion title="Conversations">
from line 277
277277param.IsNull(p.Point) // true
278278```
279279
280Request structs contain a `.SetExtraFields(map[string]any)` method which can send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching key.
280Request structs contain a `.SetExtraFields(map[string]any)` method that can send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching key.
281281
282282<Warning>
283283 For security reasons, only use `SetExtraFields` with trusted data.
from line 298
298298
299299### Request unions
300300
301Unions are represented as a struct with fields prefixed by "Of" for each of its variants. Only one field can be non-zero. The non-zero field will be serialized.
301Unions are represented as a struct with fields prefixed by "Of" for each of its variants. Only one field can be non-zero. The non-zero field is serialized.
302302
303303Subproperties of the union can be accessed through methods on the union struct. These methods return a pointer to the value, if present.
304304
from line 324
324324}
325325```
326326
327### Deserializing params
327### Deserializing parameters
328328
329329<Note>
330330 `param.SetJSON` requires SDK v1.20.0 or later.
331331</Note>
332332
333Param types (types ending in `Param`, such as `MessageNewParams` or `ToolUnionParam`) are designed for outgoing requests only. They marshal correctly to JSON but do not fully support round-trip deserialization. If you unmarshal raw JSON into a param struct, typed union fields like `OfBashTool20250124` will be nil even when the underlying JSON is valid.
333Parameter types (types ending in `Param`, such as `MessageNewParams` or `ToolUnionParam`) are designed for outgoing requests only. They marshal correctly to JSON but do not fully support round-trip deserialization. If you unmarshal raw JSON into a parameter struct, typed union fields such as `OfBashTool20250124` will be nil even when the underlying JSON is valid.
334334
335If you need to reconstruct params from raw JSON (for example, from a database, middleware, or a previous request), call `UnmarshalJSON` to populate non-union fields, then use `param.SetJSON` to attach the raw bytes for correct re-serialization:
335If you need to reconstruct parameters from raw JSON (for example, from a database, middleware, or a previous request), call `UnmarshalJSON` to populate non-union fields, then use `param.SetJSON` to attach the raw bytes for correct re-serialization:
336336
337337```go
338338// Serialize params (for example, for storage or forwarding)
from line 415
415415
416416### Response unions
417417
418In responses, unions are represented by a flattened struct containing all possible fields from each of the object variants. To convert it to a variant use the `.AsFooVariant()` method or the `.AsAny()` method if present.
418In responses, unions are represented by a flattened struct containing all possible fields from each of the object variants. To convert it to a variant, use the `.AsFooVariant()` method or the `.AsAny()` method if present.
419419
420420If a response value union contains primitive values, primitive fields will be alongside the properties but prefixed with `Of` and feature the tag `json:"...,inline"`.
421421
from line 483
483483
484484## Retries
485485
486Certain errors will be automatically retried 2 times by default, with a short exponential backoff. The SDK retries by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors.
486Certain errors are automatically retried 2 times by default, with a short exponential backoff. The SDK retries by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors.
487487
488488You can use the `WithMaxRetries` option to configure or disable this:
489489
from line 546
546546## Long requests
547547
548548<Warning>
549 Consider using the streaming Messages API for longer running requests.
549 Consider using the streaming Messages API for longer-running requests.
550550</Warning>
551551
552Avoid setting a large `MaxTokens` value without using streaming as some networks may drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/go#timeouts) without receiving a response from Anthropic.
552Avoid setting a large `MaxTokens` value without using streaming as some networks might drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/go#timeouts) without receiving a response from Anthropic.
553553
554554This SDK will also return an error if a non-streaming request is expected to be above roughly 10 minutes long. Calling `.Messages.NewStreaming()` or [setting a custom timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/go#timeouts) disables this error.
555555
556556## File uploads
557557
558Request parameters that correspond to file uploads in multipart requests are typed as `io.Reader`. The contents of the `io.Reader` will by default be sent as a multipart form part with the file name of `anonymous_file` and content type of `application/octet-stream`, so the recommended approach is to specify a custom content type with the `anthropic.File(reader io.Reader, filename string, contentType string)` helper, which wraps any `io.Reader` with the appropriate file name and content type.
558Request parameters that correspond to file uploads in multipart requests are typed as `io.Reader`. The contents of the `io.Reader` are sent by default as a multipart form part with the file name of `anonymous_file` and content type of `application/octet-stream`, so the recommended approach is to specify a custom content type with the `anthropic.File(reader io.Reader, filename string, contentType string)` helper, which wraps any `io.Reader` with the appropriate file name and content type.
559559
560560```go
561561// A file from the file system
from line 570
570570}
571571```
572572
573The file name and content type can also be customized by implementing `Name() string` or `ContentType() string` on the run-time type of `io.Reader`. Note that `os.File` implements `Name() string`, so a file returned by `os.Open` will be sent with the file name on disk.
573The file name and content type can also be customized by implementing `Name() string` or `ContentType() string` on the runtime type of `io.Reader`. Note that `os.File` implements `Name() string`, so a file returned by `os.Open` is sent with the file name on disk.
574574
575575## Pagination
576576
from line 592
592592}
593593```
594594
595Or you can use simple `.List()` methods to fetch a single page and receive a standard response object with additional helper methods like `.GetNextPage()`:
595Or you can use simple `.List()` methods to fetch a single page and receive a standard response object with additional helper methods such as `.GetNextPage()`:
596596
597597```go
598598page, err := client.Messages.Batches.List(context.TODO(), anthropic.MessageBatchListParams{
from line 627
627627)
628628```
629629
630The request option `option.WithDebugLog(nil)` may be helpful while debugging.
630The request option `option.WithDebugLog(nil)` might be helpful while debugging.
631631
632632See the [full list of request options](https://pkg.go.dev/github.com/anthropics/anthropic-sdk-go/option).
633633
from line 692
692692
693693### Making custom/undocumented requests
694694
695This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, params, or response properties, the library can still be used.
695This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, parameters, or response properties, the library can still be used.
696696
697697#### Undocumented endpoints
698698
699To make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs. `RequestOptions` on the client, such as retries, will be respected when making these requests.
699To make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs. `RequestOptions` on the client, such as retries, are respected when making these requests.
700700
701701```go
702702var (
from line 714
714714}
715715```
716716
717#### Undocumented request params
717#### Undocumented request parameters
718718
719To make requests using undocumented parameters, you may use either the `option.WithQuerySet()` or the `option.WithJSONSet()` methods.
719To make requests using undocumented parameters, you can use either the `option.WithQuerySet()` or the `option.WithJSONSet()` functions.
720720
721721```go
722722params := FooNewParams{
from line 730
730730
731731#### Undocumented response properties
732732
733To access undocumented response properties, you may either access the raw JSON of the response as a string with `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with `result.JSON.Foo.Raw()`.
733To access undocumented response properties, you can either access the raw JSON of the response as a string with `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with `result.JSON.Foo.Raw()`.
734734
735735Any fields that are not present on the response struct are saved and can be accessed through `result.JSON.ExtraFields`, which is a `map[string]respjson.Field`.
736736
cli-sdks-libraries/sdks/java Changed · +21 / -21 lines
from line 99
9999 .build();
100100```
101101
102For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
102For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
103103
104104### Configuration options
105105
from line 316
316316
317317[Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) lets you integrate external tools and functions directly into the AI model's responses. Instead of producing plain text, the model can output instructions (with parameters) for calling a tool or function when appropriate. You define JSON schemas for tools, and the model uses the schemas to determine when and how to use these tools.
318318
319The tool use feature supports a "strict" mode that guarantees that the JSON output from the AI model will conform to the JSON schema you provide in the input parameters.
319The tool use feature supports a "strict" mode that guarantees that the JSON output from the AI model conforms to the JSON schema you provide in the input parameters.
320320
321321The SDK can derive a tool and its parameters automatically from the structure of an arbitrary Java class: the class's name (converted to snake case) provides the tool name, and the class's fields define the tool's parameters.
322322
from line 381
381381
382382### Calling tools
383383
384When your tool classes are defined, add them to the message parameters using `MessageCreateParams.Builder.addTool(Class<T>)` and then call them if requested to do so in the AI model's response. `BetaToolUseBlock.input(Class<T>)` can be used to parse a tool's parameters in JSON form to an instance of your tool-defining class.
384After you define your tool classes, add them to the message parameters using `MessageCreateParams.Builder.addTool(Class<T>)` and then call them if requested to do so in the AI model's response. `BetaToolUseBlock.input(Class<T>)` can be used to parse a tool's parameters in JSON form to an instance of your tool-defining class.
385385
386386After calling the tool, use `BetaToolResultBlockParam.Builder.contentAsJson(Object)` to pass the tool's result back to the AI model:
387387
from line 432
432432
433433### Tool name conversion
434434
435Tool names are derived from the camel case tool class names (for example, `GetWeather`) and converted to snake case (for example, `get_weather`). Word boundaries begin where the current character is not the first character, is uppercase, and either the preceding character is lowercase, or the following character is lowercase. For example, `MyJSONParser` becomes `my_json_parser` and `ParseJSON` becomes `parse_json`. This conversion can be overridden using the `@JsonTypeName` annotation.
435Tool names are derived from the camel case tool class names (for example, `GetWeather`) and converted to snake case (for example, `get_weather`). Word boundaries start where the current character is not the first character, is uppercase, and either the preceding character is lowercase, or the following character is lowercase. For example, `MyJSONParser` becomes `my_json_parser` and `ParseJSON` becomes `parse_json`. This conversion can be overridden using the `@JsonTypeName` annotation.
436436
437437### Local tool JSON schema validation
438438
from line 565
565565
566566The SDK throws custom unchecked exception types:
567567
568* `AnthropicServiceException` - Base class for HTTP errors.
569* `AnthropicIoException` - I/O networking errors.
570* `AnthropicRetryableException` - Generic error indicating a failure that could be retried.
571* `AnthropicInvalidDataException` - Failure to interpret successfully parsed data (for example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it).
572* `AnthropicException` - Base class for all exceptions.
568* `AnthropicServiceException` - Base class for HTTP errors
569* `AnthropicIoException` - I/O networking errors
570* `AnthropicRetryableException` - Generic error indicating a failure that could be retried
571* `AnthropicInvalidDataException` - Failure to interpret successfully parsed data (for example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it)
572* `AnthropicException` - Base class for all exceptions
573573
574574### Status code mapping
575575
from line 615
615615Optional<String> requestId = message.requestId();
616616```
617617
618This can be used to quickly log failing requests and report them back to Anthropic. For more information on debugging requests, see [Request ID](https://platform.claude.com/docs/en/api/errors#request-id).
618This can be used to log failing requests and report them back to Anthropic. For more information on debugging requests, see [Request ID](https://platform.claude.com/docs/en/api/errors#request-id).
619619
620620## Retries
621621
from line 629
629629* 429 Rate Limit
630630* 5xx Internal
631631
632The API may also explicitly instruct the SDK to retry or not retry a request.
632The API might also explicitly instruct the SDK to retry or not retry a request.
633633
634634To set a custom number of retries, configure the client using the `maxRetries` method:
635635
from line 687
687687## Long requests
688688
689689<Warning>
690 Consider using [streaming](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#streaming) for longer running requests.
690 Consider using [streaming](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#streaming) for longer-running requests.
691691</Warning>
692692
693Avoid setting a large `maxTokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#timeouts) without receiving a response from Anthropic. The SDK periodically pings the API to keep the connection alive and reduce the impact of these networks.
693Avoid setting a large `maxTokens` value without using streaming. Some networks might drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#timeouts) without receiving a response from Anthropic. The SDK periodically pings the API to keep the connection alive and reduce the impact of these networks.
694694
695695The SDK throws an error if a non-streaming request is expected to take longer than 10 minutes. Using a [streaming method](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#streaming) or [overriding the timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#timeouts) at the client or request level disables the error.
696696
from line 832
832832These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods.
833833
834834<Warning>
835 The values passed to these methods overwrite values passed to earlier methods. For security reasons, ensure these methods are only used with trusted input data.
835 The values passed to these methods overwrite values passed to earlier methods. For security reasons, use these methods only with trusted input data.
836836</Warning>
837837
838To set undocumented parameters on nested headers, query params, or body classes:
838To set undocumented parameters on nested headers, query parameters, or body classes:
839839
840840```java
841841import com.anthropic.core.JsonValue;
from line 1037
10371037
10381038The SDK consists of three artifacts:
10391039
1040* `anthropic-java-core` - Contains core SDK logic, does not depend on OkHttp. Exposes `AnthropicClient`, `AnthropicClientAsync`, and their implementation classes, all of which can work with any HTTP client.
1040* `anthropic-java-core` - Contains core SDK logic and does not depend on OkHttp. Exposes `AnthropicClient`, `AnthropicClientAsync`, and their implementation classes, all of which can work with any HTTP client.
10411041* `anthropic-java-client-okhttp` - Depends on OkHttp. Exposes `AnthropicOkHttpClient` and `AnthropicOkHttpClientAsync`.
10421042* `anthropic-java` - Depends on and exposes the APIs of both `anthropic-java-core` and `anthropic-java-client-okhttp`. Does not have its own logic.
10431043
from line 1192
11921192 .build();
11931193```
11941194
1195Prefer the well-typed constants (for example, `Model.CLAUDE_OPUS_5`) so you get autocomplete and deprecation warnings. The `String` overloads and `of(...)` are primarily for setting the field to an undocumented or not yet supported value while waiting for an SDK release that includes it.
1195Prefer the well-typed constants (for example, `Model.CLAUDE_OPUS_5`) so you get auto-complete and deprecation warnings. The `String` overloads and `of(...)` are primarily for setting the field to an undocumented or not yet supported value while waiting for an SDK release that includes it.
11961196
11971197## Beta features
11981198
11991199Beta features are available before general release to get early feedback and test new functionality. You can check the availability of all of Claude's capabilities and tools in the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
12001200
1201You can access most beta API features through the `beta()` method on the client. To enable a particular beta feature, add the appropriate [beta header](https://platform.claude.com/docs/en/api/beta-headers) with `.addBeta()` when building the message params.
1201You can access most beta API features through the `beta()` method on the client. To enable a particular beta feature, add the appropriate [beta header](https://platform.claude.com/docs/en/api/beta-headers) with `.addBeta()` when building the message parameters.
12021202
12031203For example, to enable [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing):
12041204
from line 1234
12341234
12351235 * Allowing usage of undocumented API functionality
12361236 * Lazily validating the API response against the expected shape
1237 * Representing absent vs explicitly null values
1237 * Representing absent versus explicitly null values
12381238 </Accordion>
12391239
12401240 <Accordion title="Why doesn't the SDK use data classes?">
from line 1249
12491249 * Are verbose to handle
12501250 * Encourage error handling at the wrong level of abstraction, where nothing can be done about the error
12511251 * Are tedious to propagate because of the function coloring problem
1252 * Don't play well with lambdas (also because of the function coloring problem)
1252 * Don't work well with lambdas (also because of the function coloring problem)
12531253 </Accordion>
12541254</AccordionGroup>
12551255
from line 1259
12591259
12601260This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backward-incompatible changes may be released as minor versions:
12611261
12621. Changes to library internals which are technically public but not intended or documented for external use.
12621. Changes to library internals that are technically public but not intended or documented for external use.
126312632. Changes that aren't expected to impact the vast majority of users in practice.
12641264
12651265## Additional resources
cli-sdks-libraries/sdks/php Changed · +3 / -3 lines
from line 39
3939echo $textBlock->text;
4040```
4141
42For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
42For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
4343
4444## Value objects
4545
46It is recommended to use the static `with` constructor `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)` and named parameters to initialize value objects.
46The recommended way to initialize value objects is the static `with` constructor `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)` with named parameters.
4747
4848However, builders are also provided `(new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")`.
4949
from line 103
103103
104104Error codes are as follows:
105105
106| Cause | Error Type |
106| Cause | Error type |
107107| ---------------- | ------------------------------ |
108108| HTTP 400 | `BadRequestException` |
109109| HTTP 401 | `AuthenticationException` |
cli-sdks-libraries/sdks/python Changed · +20 / -20 lines
### Handling null versus missing fields #### Undocumented request parameters ### Handling null vs missing fields #### Undocumented request params
from line 69
6969 Consider using [python-dotenv](https://pypi.org/project/python-dotenv/) to add `ANTHROPIC_API_KEY="my-anthropic-api-key"` to your `.env` file so that your API key isn't stored in source control.
7070</Tip>
7171
72For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
72For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
7373
7474## Async usage
7575
from line 202
202202
203203Streaming with `client.messages.stream(...)` exposes various helpers including accumulation and SDK-specific events.
204204
205Alternatively, you can use `client.messages.create(..., stream=True)` which only returns an iterable of the events in the stream and uses less memory (it doesn't build up a final message object for you).
205Alternatively, you can use `client.messages.create(..., stream=True)`, which only returns an iterable of the events in the stream and uses less memory (it doesn't build up a final message object for you).
206206
207207## Token counting
208208
from line 347
347347
348348## Handling errors
349349
350When the library is unable to connect to the API, or if the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of `APIError` is raised:
350When the library is unable to connect to the API, or if the API returns a non-success status code (that is, a 4xx or 5xx response), a subclass of `APIError` is raised:
351351
352352```python
353353import anthropic
from line 392
392392
393393> For more information on debugging requests, see [Request ID](https://platform.claude.com/docs/en/api/errors#request-id).
394394
395All object responses in the SDK provide a `_request_id` property which is added from the `request-id` response header so that you can quickly log failing requests and report them back to Anthropic.
395All object responses in the SDK provide a `_request_id` property, which is added from the `request-id` response header so that you can log failing requests and report them back to Anthropic.
396396
397397```python
398398message = client.messages.create(
from line 400
400400 messages=[{"role": "user", "content": "Hello, Claude"}],
401401 model="claude-opus-5-5",
402402)
403print(message._request_id) # e.g., req_018EeWyXxfu5pfWkrYcMdjWG
403print(message._request_id) # for example, req_018EeWyXxfu5pfWkrYcMdjWG
404404```
405405
406406<Note>
from line 460
460460## Long requests
461461
462462<Warning>
463 Consider using the streaming [Messages API](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#streaming-responses) for longer running requests.
463 Consider using the [streaming Messages API](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#streaming-responses) for longer-running requests.
464464</Warning>
465465
466Avoid setting a large `max_tokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#timeouts) without receiving a response from Anthropic.
466Avoid setting a large `max_tokens` value without using streaming. Some networks might drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#timeouts) without receiving a response from Anthropic.
467467
468468The SDK will throw a `ValueError` if a non-streaming request is expected to take longer than approximately 10 minutes. Passing `stream=True` or overriding the `timeout` option at the client or request level disables this error.
469469
470An expected request latency longer than the [timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#timeouts) for a non-streaming request will result in the client terminating the connection and retrying without receiving a response.
470An expected request latency longer than the [timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#timeouts) for a non-streaming request will result in the client ending the connection and retrying without receiving a response.
471471
472472The SDK sets a [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) option to reduce the impact of idle connection timeouts on some networks. This can be overridden by passing a custom `http_client` option to the client.
473473
from line 530
530530If you need to, you can override it by setting default headers on the client object or per-request.
531531
532532<Warning>
533 Overriding default headers may result in incorrect types and other unexpected or undefined behavior in the SDK.
533 Overriding default headers might result in incorrect types and other unexpected or undefined behavior in the SDK.
534534</Warning>
535535
536536```python
from line 552
552552
553553### Request parameters
554554
555Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also have helper methods for things like serializing back into JSON ([`v1`](https://docs.pydantic.dev/1.10/usage/models/), [`v2`](https://docs.pydantic.dev/latest/concepts/serialization/)).
555Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev), which also have helper methods for things such as serializing back into JSON ([Pydantic `v1`](https://docs.pydantic.dev/1.10/usage/models/), [Pydantic `v2`](https://docs.pydantic.dev/latest/concepts/serialization/)).
556556
557Typed requests and responses provide autocomplete and documentation within your editor. If you'd like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
557Typed requests and responses provide auto-complete and documentation within your editor. If you'd like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
558558
559559### Response models
560560
from line 570
570570data = message.to_dict()
571571```
572572
573### Handling null vs missing fields
573### Handling null versus missing fields
574574
575575In responses, you can distinguish between fields that are explicitly `null` versus fields that were not returned (missing):
576576
from line 627
627627 print(line)
628628```
629629
630The context manager is required so that the response will reliably be closed.
630The context manager is required so that the response is reliably closed.
631631
632632### Logging
633633
from line 641
641641
642642### Making custom/undocumented requests
643643
644This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, params, or response properties, the library can still be used.
644This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, parameters, or response properties, the library can still be used.
645645
646646#### Undocumented endpoints
647647
from line 659
659659print(response.json())
660660```
661661
662#### Undocumented request params
662#### Undocumented request parameters
663663
664664If you want to explicitly send an extra parameter, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request options.
665665
666666<Warning>
667 The `extra_` parameters override documented parameters of the same name. For security reasons, ensure these methods are only used with trusted input data.
667 The `extra_` parameters override documented parameters of the same name. For security reasons, use these methods only with trusted input data.
668668</Warning>
669669
670670#### Undocumented response properties
671671
672To access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You can also get all extra fields on the Pydantic model as a dict with `response.model_extra`.
672To access undocumented response properties, you can access the extra fields such as `response.unknown_prop`. You can also get all extra fields on the Pydantic model as a dict with `response.model_extra`.
673673
674674### Configuring the HTTP client
675675
from line 703
703703
704704### Managing HTTP resources
705705
706By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
706By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if you want to, or with a context manager that closes when exiting.
707707
708708```python
709709with Anthropic() as client:
from line 764
764764This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backward-incompatible changes may be released as minor versions:
765765
7667661. Changes that only affect static types, without breaking runtime behavior.
7672. Changes to library internals which are technically public but not intended or documented for external use.
7672. Changes to library internals that are technically public but not intended or documented for external use.
7687683. Changes that aren't expected to impact the vast majority of users in practice.
769769
770770### Determining the installed version
cli-sdks-libraries/sdks/ruby Changed · +16 / -16 lines
### Undocumented request parameters ### Undocumented request params
from line 40
4040end
4141```
4242
43For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
43For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
4444
4545## Streaming
4646
from line 80
8080
8181## Input schema and tool calling
8282
83The SDK provides helper mechanisms to define structured data classes for tools and let Claude automatically execute them. For detailed documentation on tool use patterns including the tool runner, see [Tool Runner (SDK)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner).
83The SDK provides helper mechanisms to define structured data classes for tools and let Claude automatically run them. For detailed documentation on tool use patterns including the tool runner, see [Tool Runner (SDK)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner).
8484
8585```ruby
8686anthropic = Anthropic::Client.new
from line 113
113113
114114## Handling errors
115115
116When the library is unable to connect to the API, or if the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of `Anthropic::Errors::APIError` is raised:
116When the library is unable to connect to the API, or if the API returns a non-success status code (that is, a 4xx or 5xx response), a subclass of `Anthropic::Errors::APIError` is raised:
117117
118118```ruby
119119anthropic = Anthropic::Client.new
from line 136
136136
137137Error codes are as follows:
138138
139| Cause | Error Type |
139| Cause | Error type |
140140| ---------------- | -------------------------- |
141141| HTTP 400 | `BadRequestError` |
142142| HTTP 401 | `AuthenticationError` |
from line 152
152152
153153## Retries
154154
155Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
155Certain errors are automatically retried 2 times by default, with a short exponential backoff.
156156
157157Connection errors (for example, because of a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts are all retried by default.
158158
from line 236
236236anthropic = Anthropic::Client.new
237237require "pathname"
238238
239# Use `Pathname` to send the filename and/or avoid paging a large file into memory:
239# Use `Pathname` to send the filename, avoid paging a large file into memory, or both:
240240file_metadata = anthropic.files.upload(file: Pathname("/path/to/file"))
241241
242242# Alternatively, pass file contents or a `StringIO` directly:
243243file_metadata = anthropic.files.upload(file: File.read("/path/to/file"))
244244
245# Or, to control the filename and/or content type:
245# Or, to control the filename, the content type, or both:
246246file = Anthropic::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "...")
247247file_metadata = anthropic.files.upload(file: file)
248248
from line 249
249249puts(file_metadata.id)
250250```
251251
252Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
252Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't determine whether the descriptor is a file or pipe (which cannot be rewound).
253253
254254## Sorbet
255255
256256This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
257257
258You can provide typesafe request parameters like so:
258You can provide typesafe request parameters as follows:
259259
260260```ruby
261261anthropic = Anthropic::Client.new
from line 335
335335
336336The `Anthropic::Client` instances are threadsafe, but are only fork-safe when there are no in-flight HTTP requests.
337337
338Each instance of `Anthropic::Client` has its own HTTP connection pool with a default size of 99. As such, the recommendation is to create the client once per application in most settings.
338Each instance of `Anthropic::Client` has its own HTTP connection pool with a default size of 99. As such, the recommendation is to create the client once for each application in most settings.
339339
340340When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting toward the request timeout.
341341
from line 345
345345
346346### Undocumented properties
347347
348You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
348You can send undocumented parameters to any endpoint, and read undocumented response properties, as follows:
349349
350350<Warning>
351 The `extra_` parameters of the same name override the documented parameters. For security reasons, ensure these methods are only used with trusted input data.
351 The `extra_` parameters of the same name override the documented parameters. For security reasons, use these methods only with trusted input data.
352352</Warning>
353353
354354```ruby
from line 369
369369puts(message[:my_undocumented_property])
370370```
371371
372### Undocumented request params
372### Undocumented request parameters
373373
374If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the previous examples.
374If you want to explicitly send an extra parameter, you can do so with `extra_query`, `extra_body`, and `extra_headers` under `request_options:` when making a request, as seen in the previous examples.
375375
376376### Undocumented endpoints
377377
378To make requests to undocumented endpoints while retaining the benefit of authentication, retries, and so on, you can make requests using `anthropic.request`, like so:
378To make requests to undocumented endpoints while retaining the benefit of authentication, retries, and so on, you can make requests using `anthropic.request`, as follows:
379379
380380```ruby
381381response = anthropic.request(
cli-sdks-libraries/sdks/typescript Changed · +25 / -25 lines
from line 55
5555}
5656```
5757
58For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) with access to multiple workspaces, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
58For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
5959
6060## Request and response types
6161
62This library includes TypeScript definitions for all request parameters and response fields. You may import and use them like so:
62This library includes TypeScript definitions for all request parameters and response fields. You can import and use them as follows:
6363
6464```typescript
6565const client = new Anthropic({
from line 136
136136console.log(message);
137137```
138138
139Streaming with `client.messages.stream(...)` exposes various helpers for your convenience including event handlers and accumulation.
139Streaming with `client.messages.stream(...)` exposes various helpers for your convenience, including event handlers and accumulation.
140140
141Alternatively, you can use `client.messages.create({ ..., stream: true })` which only returns an async iterable of the events in the stream and thus uses less memory (it does not build up a final message object for you).
141Alternatively, you can use `client.messages.create({ ..., stream: true })`, which only returns an async iterable of the events in the stream and thus uses less memory (it does not build up a final message object for you).
142142
143143## Tool helpers
144144
145This SDK provides helpers for making it easy to create and run tools in the Messages API. You can use Zod schemas or JSON Schemas to describe the input to a tool. You can then run those tools using the `client.beta.messages.toolRunner()` method. This method handles passing the inputs generated by the chosen model into the right tool and passing the result back to the model.
145This SDK provides helpers for creating and running tools in the Messages API. You can use Zod schemas or JSON Schemas to describe the input to a tool. You can then run those tools using the `client.beta.messages.toolRunner()` method. This method handles passing the inputs generated by the chosen model into the right tool and passing the result back to the model.
146146
147147For more details on tool use, see [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview). To run the browser use tool or the computer use tool with this SDK, see [Browser and computer use with the SDK toolsets](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-sdk).
148148
from line 314
314314
315315### Getting results from a batch
316316
317Once a Message Batch has been processed, indicated by `.processing_status === 'ended'`, you can access the results with `.batches.results()`
317Once a Message Batch has been processed, indicated by `.processing_status === 'ended'`, you can access the results with `.batches.results()`:
318318
319319```typescript
320320const results = await client.messages.batches.results(batch.id);
from line 334
334334* an `fs.ReadStream`
335335* the return value of the `toFile` helper
336336
337Set the content type explicitly as the Files API will not infer it for you:
337Set the content type explicitly as the Files API does not infer it for you:
338338
339339```typescript
340340import fs from "node:fs";
from line 369
369369
370370## Handling errors
371371
372When the library is unable to connect to the API, or if the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of `APIError` is thrown:
372When the library is unable to connect to the API, or if the API returns a non-success status code (that is, a 4xx or 5xx response), a subclass of `APIError` is thrown:
373373
374374```typescript
375375const message = await client.messages
from line 407
407407
408408> For more information on debugging requests, see [Request ID](https://platform.claude.com/docs/en/api/errors#request-id).
409409
410All object responses in the SDK provide a `_request_id` property which is added from the `request-id` response header so that you can quickly log failing requests and report them back to Anthropic.
410All object responses in the SDK provide a `_request_id` property, which is added from the `request-id` response header so that you can log failing requests and report them back to Anthropic.
411411
412412```typescript
413413const message = await client.messages.create({
from line 443
443443
444444## Timeouts
445445
446By default requests time out after 10 minutes. However if you have specified a large `max_tokens` value and are *not* streaming, the default timeout will be calculated dynamically using the formula:
446By default requests time out after 10 minutes. However, if you have specified a large `max_tokens` value and are *not* streaming, the default timeout will be calculated dynamically using the formula:
447447
448448```typescript
449449const minimum = 10 * 60;
from line 479
479479## Long requests
480480
481481<Warning>
482 Consider using the streaming [Messages API](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#streaming-responses) for longer running requests.
482 Consider using the [streaming Messages API](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#streaming-responses) for longer-running requests.
483483</Warning>
484484
485Avoid setting a large `max_tokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) without receiving a response from Anthropic.
485Avoid setting a large `max_tokens` value without using streaming. Some networks might drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) without receiving a response from Anthropic.
486486
487487This SDK also throws an error if a non-streaming request is expected to be above roughly 10 minutes long. Passing `stream: true` or [overriding](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) the `timeout` option at the client or request level disables this error.
488488
489An expected request latency longer than the [timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) for a non-streaming request will result in the client terminating the connection and retrying without receiving a response.
489An expected request latency longer than the [timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) for a non-streaming request will result in the client ending the connection and retrying without receiving a response.
490490
491491When supported by the `fetch` implementation, the SDK sets a [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) option to reduce the impact of idle connection timeouts on some networks. This can be [overridden](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#configuring-proxies) by configuring a custom proxy.
492492
from line 526
526526
527527If you need to, you can override it by setting default headers on a per-request basis.
528528
529Be aware that doing so may result in incorrect types and other unexpected or undefined behavior in the SDK.
529Be aware that doing so might result in incorrect types and other unexpected or undefined behavior in the SDK.
530530
531531```typescript
532532const client = new Anthropic();
from line 547
547547
548548The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return. This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
549549
550You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data. Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
550You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data. Unlike `.asResponse()`, this method consumes the body, returning once it is parsed.
551551
552552```typescript
553553const client = new Anthropic();
from line 584
584584You can configure the log level in two ways:
585585
5865861. Through the `ANTHROPIC_LOG` environment variable
5872. Using the `logLevel` client option (overrides the environment variable if set)
5872. Through the `logLevel` client option (overrides the environment variable if set)
588588
589589```typescript
590590const client = new Anthropic({
from line 600
600600* `'error'` - Show only errors
601601* `'off'` - Disable all logging
602602
603At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies. Some authentication-related headers are redacted, but sensitive data in request and response bodies may still be visible.
603At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies. Some authentication-related headers are redacted, but sensitive data in request and response bodies might still be visible.
604604
605605#### Custom logger
606606
607607By default, this library logs to `globalThis.console`. You can also provide a custom logger. Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, open an issue.
608608
609When providing a custom logger, the `logLevel` option still controls which messages are emitted; messages below the configured level will not be sent to your logger.
609When providing a custom logger, the `logLevel` option still controls which messages are emitted; messages below the configured level are not sent to your logger.
610610
611611```typescript
612612import pino from "pino";
from line 621
621621
622622### Making custom/undocumented requests
623623
624This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, params, or response properties, the library can still be used.
624This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, parameters, or response properties, the library can still be used.
625625
626626#### Undocumented endpoints
627627
from line 636
636636
637637#### Undocumented request parameters
638638
639To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you send will be sent as-is.
639To make requests using undocumented parameters, you can use `// @ts-expect-error` on the undocumented parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you send are sent as-is.
640640
641641```typescript
642642client.messages.create({
from line 646
646646});
647647```
648648
649For requests with the `GET` verb, any extra parameters will be in the query; all other requests will send the extra parameter in the body.
649For requests with the `GET` verb, any extra parameters are in the query; all other requests send the extra parameter in the body.
650650
651651If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request options.
652652
653653#### Undocumented response properties
654654
655To access undocumented response properties, you may access the response object with `// @ts-expect-error` on the response object, or cast the response object to the requisite type. Like the request parameters, the SDK does not validate or strip extra properties from the response from the API.
655To access undocumented response properties, you can access the response object with `// @ts-expect-error` on the response object, or cast the response object to the requisite type. Like the request parameters, the SDK does not validate or strip extra properties from the response from the API.
656656
657657### Customizing the fetch client
658658
659By default, this library expects a global `fetch` function is defined.
659By default, this library requires a global `fetch` function to be defined.
660660
661661If you want to use a different `fetch` function, you can either polyfill the global:
662662
from line 787
787787This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backward-incompatible changes may be released as minor versions:
788788
7897891. Changes that only affect static types, without breaking runtime behavior.
7902. Changes to library internals which are technically public but not intended or documented for external use.
7902. Changes to library internals that are technically public but not intended or documented for external use.
7917913. Changes that aren't expected to impact the vast majority of users in practice.
792792
793793Backward compatibility is taken seriously to ensure you can rely on a smooth upgrade experience.
get-api-key Changed · +5 / -5 lines
from line 8
88
99## Choose a key type
1010
11When you create a key, you choose its type, which determines what the key can do, where it works, and when it stops working. A **personal key** acts as you, and stops working if you leave an organization. A **service account key** represents a [service account](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#service-accounts) which can be used by workloads such as CI pipelines, production services, or agents. Use a personal key for your own development, and a service account key for anything shared.
11When you create a key, you choose its type, which determines what the key can do, where it works, and when it stops working. A **personal key** acts as you, and stops working if you leave an organization. A **service account key** represents a [service account](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#service-accounts), which can be used by workloads such as CI pipelines, production services, or agents. Use a personal key for your own development, and a service account key for anything shared.
1212
1313You can also create a **workspace key**, a legacy key without an owner: it belongs to the workspace you create it in and keeps working after its creator leaves. It is preferable to use a personal or service account key, as these stop working automatically when their associated account is removed from the organization.
1414
from line 24
2424 </Step>
2525
2626 <Step title="Create a key">
27 Click **Create key**, name the key, choose an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration), and set **Linked account** to yourself or a service account. You can also choose a [workspace](https://platform.claude.com/settings/workspaces) in the Console to scope the key to.
27 Click **Create key**, name the key, select an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration), and set **Linked account** to yourself or a service account. You can also select a [workspace](https://platform.claude.com/settings/workspaces) in the Console to scope the key to.
2828 </Step>
2929
3030 <Step title="Copy and store the key">
from line 32
3232 </Step>
3333</Steps>
3434
35If the **Create key** button on the API keys page is disabled, your role may not allow you to create keys there. Ask an organization admin to change your role, or to create a service account key for your workload.
35If the **Create key** button on the API keys page is disabled, your role might not allow you to create keys there. Ask an organization admin to change your role, or to create a service account key for your workload.
3636
3737## Use your API key
3838
from line 42
4242export ANTHROPIC_API_KEY="sk-ant-api03-..."
4343```
4444
45The [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) reads `ANTHROPIC_API_KEY` automatically. Direct HTTP requests send the key as `Authorization: Bearer <key>`. If your API key works on multiple workspaces, you must also send the `anthropic-workspace-id` header on each Claude API request, as shown in [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). For the Admin API, see [API keys and the Admin API](https://platform.claude.com/docs/en/get-api-key#api-keys-and-the-admin-api).
45The [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) reads `ANTHROPIC_API_KEY` automatically. Direct HTTP requests send the key as `Authorization: Bearer <key>`. If your API key isn't scoped to a workspace, you must also send the `anthropic-workspace-id` header on each Claude API request, as shown in [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). For the Admin API, see [API keys and the Admin API](https://platform.claude.com/docs/en/get-api-key#api-keys-and-the-admin-api).
4646
47To make your first request, follow the [Quickstart](https://platform.claude.com/docs/en/get-started), and see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication) for the full picture, including short-lived credentials with Workload Identity Federation.
47To make your first request, follow the [Quickstart](https://platform.claude.com/docs/en/get-started), and see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication) for complete details, including short-lived credentials with Workload Identity Federation.
4848
4949## API keys and the Admin API
5050
intro Changed · +4 / -4 lines
from line 32
3232
3333## Recommended path for new developers
3434
35Follow these steps to go from zero to a working Claude integration.
35Follow these steps to build a working Claude integration.
3636
3737<Steps>
3838 <Step title="Make your first API call">
from line 77
7777 Explore and understand the API in your browser with playground.
7878 </Card>
7979
80 <Card title="API Reference" icon="code" href="https://platform.claude.com/docs/en/api/overview">
80 <Card title="API reference" icon="code" href="https://platform.claude.com/docs/en/api/overview">
8181 Explore the full Claude API and client SDK documentation.
8282 </Card>
8383
from line 90
9090
9191## Key capabilities
9292
93Claude can assist with many tasks that involve text, code, and images.
93Claude can help with many tasks that involve text, code, and images.
9494
9595<CardGroup cols={2}>
9696 <Card title="Text and code generation" icon="text-aa" href="https://platform.claude.com/docs/en/build-with-claude/overview">
from line 111
111111 Find answers to frequently asked account and billing questions.
112112 </Card>
113113
114 <Card title="Service Status" icon="chart" href="https://status.claude.com">
114 <Card title="Service status" icon="chart" href="https://status.claude.com">
115115 Check the status of Anthropic services.
116116 </Card>
117117</CardGroup>
manage-claude/access-transparency Changed · +12 / -12 lines
from line 19
1919
2020Anthropic personnel access customer content only under defined conditions. Access Transparency is designed to make such access visible to you. The design rests on the following principles:
2121
22* **Human access happens only under a published reason code.**
22* **Human access occurs only under a published reason code.**
2323* **Human views of your covered content are recorded.** Anthropic's internal tooling that can reach your covered content is instrumented to emit an event on each view.
2424* **Events represent human access, not automated processing.** Anthropic's automated safety systems process your content in a secured pipeline with no interactive human access; that processing does not generate `anthropic_access` events. The one event automated processing can initiate is a `cmek_preserve` preservation record (see [CMEK content preservation](https://platform.claude.com/docs/en/manage-claude/access-transparency#cmek-content-preservation)).
2525* **Events arrive on your existing feed.** Activities are accessible through your [Compliance API Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed). Existing credentials, audit, export, and SIEM integrations for the Compliance API still apply.
from line 27
2727
2828## What Access Transparency covers
2929
30* **Covered content:** Access Transparency covers prompt and response content sent through the Claude Messages API or Claude Code sessions. Anthropic's [general ZDR documentation](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention) explains which APIs and features are covered by ZDR. The same APIs and features are covered by Access Transparency.
30* **Covered content:** Access Transparency covers prompt and response content sent through the Claude Messages API or Claude Code sessions. The [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention) page explains which APIs and features are covered by ZDR. The same APIs and features are covered by Access Transparency.
3131* **Manual views by Anthropic personnel:** Manual views of your covered content by Anthropic reviewers generate events.
3232
3333## What Access Transparency does not cover
from line 68
6868 "https://api.anthropic.com/v1/compliance/activities" \
6969 --data-urlencode "activity_types[]=anthropic_access" \
7070 --data-urlencode "limit=50" \
71 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
72 --header "anthropic-version: 2023-06-01"
71 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
72 -H "anthropic-version: 2023-06-01"
7373```
7474
7575Pagination, date-range filtering (`created_at.gte` / `.lt`), and the response envelope (`has_more`, `first_id`, `last_id`) are shared with the rest of the Activity Feed. See [Query the Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed).
from line 126
126126 "https://api.anthropic.com/v1/compliance/activities" \
127127 --data-urlencode "activity_types[]=cmek_preserve" \
128128 --data-urlencode "limit=50" \
129 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
130 --header "anthropic-version: 2023-06-01"
129 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
130 -H "anthropic-version: 2023-06-01"
131131```
132132
133133Example JSON message:
from line 182
182182
183183### Coverage timing
184184
185Access Transparency applies from the time it is enabled for your organization. Content already in your retention window at enablement might also generate events when accessed, but Anthropic does not guarantee coverage for content written before enablement. Treat your enablement date as the start of reliable coverage. There might be a delay of up to two hours between enabling Access Transparency and your content being covered.
185Access Transparency applies from the time it is enabled for your organization. Content already in your retention window at enablement might also generate events when accessed, but Anthropic does not guarantee coverage for content written before enablement. Treat your enablement date as the start of reliable coverage. There might be a delay of up to 2 hours between enabling Access Transparency and your content being covered.
186186
187187### Notification timing
188188
189`anthropic_access` and `cmek_preserve` events are delivered to your Compliance API feed within two business days of the access or preservation they record. This feed should not be treated as a real-time alerting channel, and the `accessed_at` timestamp reflects when the access occurred, which might be up to two business days before the activity becomes visible in your feed. The `created_at` field reflects the time Anthropic recorded the event, and the event usually becomes visible in your feed shortly after that time. These events do not follow the Activity Feed's usual 1-minute [indexing lag](https://platform.claude.com/docs/en/manage-claude/compliance-integration-patterns#window-polling): an event can become visible up to two business days after its `created_at`. If you poll the feed by `created_at` window, overlap consecutive windows by at least two business days for `anthropic_access` and `cmek_preserve` events so that a late-indexed event is not dropped.
189`anthropic_access` and `cmek_preserve` events are delivered to your Compliance API feed within 2 business days of the access or preservation they record. This feed should not be treated as a real-time alerting channel, and the `accessed_at` timestamp reflects when the access occurred, which might be up to 2 business days before the activity becomes visible in your feed. The `created_at` field reflects the time Anthropic recorded the event, and the event usually becomes visible in your feed shortly after that time. These events do not follow the Activity Feed's usual 1-minute [indexing lag](https://platform.claude.com/docs/en/manage-claude/compliance-integration-patterns#window-polling): an event can become visible up to 2 business days after its `created_at`. If you poll the feed by `created_at` window, overlap consecutive windows by at least 2 business days for `anthropic_access` and `cmek_preserve` events so that a late-indexed event is not dropped.
190190
191191### Automated processing does not generate access events
192192
from line 215
215215 Access Transparency is not available for platform deployments. Contact your Anthropic account representative to discuss your use case.
216216 </Accordion>
217217
218 <Accordion title="Will I see events for access that happened before we enrolled, or for our older data?">
218 <Accordion title="Will I see events for access that occurred before we enrolled, or for our older data?">
219219 Access Transparency is not guaranteed to be retroactive. It covers human access to content written to the Claude API on or after your enrollment date. You might see events for access to content that was written before enrollment.
220220 </Accordion>
221221
222222 <Accordion title="How soon after an access will I see the event?">
223 Within two business days of the access. Configure any SIEM alerting or scheduled exports with a matching lookback window rather than assuming real-time arrival.
223 Within 2 business days of the access. Configure any SIEM alerting or scheduled exports with a matching lookback window rather than assuming real-time arrival.
224224 </Accordion>
225225
226226 <Accordion title="How do I know which request an anthropic_access event refers to?">
from line 232
232232 </Accordion>
233233
234234 <Accordion title="How does Access Transparency relate to CMEK?">
235 They are independent. With CMEK, safety preservation outside your key emits a separate `cmek_preserve` event on the same feed. See [CMEK content preservation](https://platform.claude.com/docs/en/manage-claude/access-transparency#cmek-content-preservation) and [CMEK](https://platform.claude.com/docs/en/manage-claude/cmek).
235 They are independent. With CMEK, safety preservation outside your key emits a separate `cmek_preserve` event on the same feed. See [CMEK content preservation](https://platform.claude.com/docs/en/manage-claude/access-transparency#cmek-content-preservation) and [Customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek).
236236 </Accordion>
237237
238238 <Accordion title="How can I tell that my Access Transparency record has not been altered?">
from line 250
250250* [Compliance API overview](https://platform.claude.com/docs/en/manage-claude/compliance-api)
251251* [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed)
252252* [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention)
253* [Customer-Managed Encryption Keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek)
253* [Customer-managed encryption keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek)
254254* [Claude Code data usage](https://code.claude.com/docs/en/data-usage)
255255* [Trust Center](https://trust.anthropic.com/resources)
256256
manage-claude/access-transparency-log Changed · +27 / -27 lines
from line 20
2020
2121A transparency log is a technique for making a record tamper-evident. Entries are only ever appended. Each time the log grows, its operator signs a short statement, called a checkpoint, that commits to every entry so far through a Merkle tree hash. Anyone who keeps a checkpoint can later demand proof that the current log still contains everything that checkpoint covered, unchanged and in the same order. Removing or rewriting an entry therefore cannot go unnoticed by a verifier who kept a checkpoint that covered that entry. Certificate Transparency and the Go module checksum database are built on the same technique. [C2SP tlog-tiles](https://c2sp.org/tlog-tiles) is an open specification for serving such a log as signed checkpoints plus static, cacheable tiles of hashes and entries, so that clients can fetch the hashes and compute every proof themselves.
2222
23When Access Transparency is enabled, Anthropic maintains a transparency log for your organization. It is an append-only, cryptographically signed record of Access Transparency events (`anthropic_access` and `cmek_preserve`). Each such event recorded for your organization after the log was created is appended to it. The log follows the C2SP tlog-tiles format, so tooling built for that standard understands its checkpoints, tiles, and proofs.
23When Access Transparency is enabled, Anthropic maintains a transparency log for your organization. It is an append-only, cryptographically signed record of Access Transparency events (`anthropic_access` and `cmek_preserve`). Each such event recorded for your organization after the log was created is appended to it. The log follows the C2SP tlog-tiles format, so tooling built for that standard can parse its checkpoints, tiles, and proofs.
2424
25* **One log per organization.** Each organization's log has a fixed origin string: `axt.anthropic.com/<your organization UUID>`. The origin never changes for the life of the organization.
25* **One log for each organization.** Each organization's log has a fixed origin string: `axt.anthropic.com/<your organization UUID>`. The origin never changes for the life of the organization.
2626* **Every new event becomes a leaf.** When an Access Transparency event becomes eligible to appear on your Activity Feed, it is first appended to your log as a leaf, and only then served on the feed. A leaf is a deterministic serialization of the event's documented fields. The event on your feed carries `transparency_log_leaf_index`, its zero-based position in your log.
2727* **Checkpoints commit to the whole history.** The log is a Merkle tree. Whenever it grows, Anthropic publishes a signed checkpoint: a short text document stating the log's origin, its current size, and the root hash that commits to every leaf. Each checkpoint carries exactly one signature from the log's signing key.
2828* **Two proofs follow.** An inclusion proof shows that a specific event is present at its position under a checkpoint. A consistency proof shows that a later checkpoint is an append-only extension of an earlier one you saved, so nothing between them was removed or changed.
from line 53
5353
5454## Timing
5555
56* **Events:** Access Transparency events appear on your Activity Feed within two business days of the access. An event enters the log only once it is eligible to be served, so the log never reveals an event early. Because the log is written before the feed serves the event, an entry can briefly appear in the log before its event appears on your feed. That gap is not a discrepancy.
56* **Events:** Access Transparency events appear on your Activity Feed within 2 business days of the access. An event enters the log only once it is eligible to be served, so the log never reveals an event early. Because the log is written before the feed serves the event, an entry can briefly appear in the log before its event appears on your feed. That gap is not a discrepancy.
5757* **Checkpoints:** A new checkpoint is published whenever your log grows.
5858* **Inclusion proofs:** A proof for a newly served event is available once a checkpoint covering the event's position is published, normally very shortly after the event appears. If you request one sooner, you receive a `404` and retry after a short delay.
5959* **Verification cadence:** Run your verification at least daily. Hourly is reasonable.
from line 96
9696
9797### Errors
9898
99Errors use the standard Compliance API JSON error envelope on every endpoint, including the text and binary ones. See [Errors](https://platform.claude.com/docs/en/manage-claude/compliance-errors) for the envelope and the shared error types.
99Errors use the standard Compliance API JSON error envelope on every endpoint, including the text and binary ones. See [Handle Compliance API errors](https://platform.claude.com/docs/en/manage-claude/compliance-errors) for the envelope and the shared error types.
100100
101101| Status | Meaning on this surface |
102102| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
from line 118
118118```bash
119119curl --fail-with-body -sS \
120120 "https://api.anthropic.com/v1/compliance/transparency_log/checkpoint" \
121 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
122 --header "anthropic-version: 2023-06-01"
121 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
122 -H "anthropic-version: 2023-06-01"
123123```
124124
125125The response is `text/plain`: a C2SP [signed note](https://c2sp.org/signed-note). The body lines are the origin, the tree size in decimal, and the base64 root hash. A blank line follows, then the signature line, which starts with an em dash (U+2014), names the origin, and ends with a base64 value. Values here are illustrative:
from line 132
132132— axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b q83vATBFAiEAvL8m…(base64)…
133133```
134134
135* The first four bytes of the decoded signature value are the signing key's `key_hash`, which tells you which entry in the [verifier key set](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#read-the-verifier-keys) to verify with. The remaining bytes are an ASN.1 DER ECDSA P-256 signature over the SHA-256 of the note body: every byte before the blank line, including the body's trailing newline.
135* The first 4 bytes of the decoded signature value are the signing key's `key_hash`, which tells you which entry in the [verifier key set](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#read-the-verifier-keys) to verify with. The remaining bytes are an ASN.1 DER ECDSA P-256 signature over the SHA-256 of the note body: every byte before the blank line, including the body's trailing newline.
136136* A checkpoint can carry additional lines after the root hash. Ignore lines you do not understand. They are covered by the signature.
137137* Ignore a signature line whose name is not your origin or whose key hash you do not hold.
138138* Never cache a checkpoint. A stale one hides the log's current size, so newly served events look uncovered.
from line 144
144144```bash
145145curl --fail-with-body -sS \
146146 "https://api.anthropic.com/v1/compliance/transparency_log/keys" \
147 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
148 --header "anthropic-version: 2023-06-01"
147 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
148 -H "anthropic-version: 2023-06-01"
149149```
150150
151151```json
from line 170
170170| `origin` | string | The origin line every checkpoint of this log carries. Informational: compare checkpoints against the origin you derive yourself, not against this field |
171171| `log_keys` | array | The key that signs new checkpoints first, then every other key the log serves, newest first. Never empty |
172172| `log_keys[].verifier_key` | string | The key as a C2SP note-verifier string, `<origin>+<key_hash>+<base64 key>`, accepted by tlog-tiles tooling that supports ECDSA note keys (for example, the Go `github.com/transparency-dev/formats` module). The base64 part decodes to the algorithm byte `0x02` followed by the DER-encoded public key |
173| `log_keys[].key_hash` | string | Eight lowercase hex digits. The 4-byte selector that matches this key to a checkpoint's signature line. It is the first four bytes of `fingerprint` and is not an identity |
173| `log_keys[].key_hash` | string | Eight lowercase hex digits. The 4-byte selector that matches this key to a checkpoint's signature line. It is the first 4 bytes of `fingerprint` and is not an identity |
174174| `log_keys[].fingerprint` | string | 64 lowercase hex digits: the SHA-256 of the DER `SubjectPublicKeyInfo` |
175175| `log_keys[].algorithm` | string | The key type, currently `ecdsa_p256_sha256`. Values may be added. Skip a key whose algorithm you do not support |
176176| `log_keys[].public_key` | string | The public key as base64 DER `SubjectPublicKeyInfo` |
177177
178The `key_hash` covers only the key bytes: it is the first four bytes of SHA-256 over the DER `SubjectPublicKeyInfo`, which is the rule the ECDSA note-verifier encoding uses. It is not the name-dependent key ID that the base signed-note format defines for Ed25519 keys, so it does not change with the origin. A valid signature by a key listed in [Published key fingerprints](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#published-key-fingerprints) proves the checkpoint came from Anthropic's transparency log service. The origin line inside the signed checkpoint is what binds it to your organization. That is why you compare that line against the origin you derive yourself.
178The `key_hash` covers only the key bytes: it is the first 4 bytes of SHA-256 over the DER `SubjectPublicKeyInfo`, which is the rule the ECDSA note-verifier encoding uses. It is not the name-dependent key ID that the base signed-note format defines for Ed25519 keys, so it does not change with the origin. A valid signature by a key listed in [Published key fingerprints](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#published-key-fingerprints) proves the checkpoint came from Anthropic's transparency log service. The origin line inside the signed checkpoint is what binds it to your organization. That is why you compare that line against the origin you derive yourself.
179179
180180Keys can rotate:
181181
from line 185
185185
186186#### Published key fingerprints
187187
188Anthropic publishes the fingerprint of every key that signs checkpoints here, outside the API. This lets you check a key you hold locally against a source the serving path cannot alter. The key you hold may come from an earlier `GET /keys` response or from tooling that pins the key.
188Anthropic publishes the fingerprint of every key that signs checkpoints here, outside the API. This lets you check a key you hold locally against a source the serving path cannot alter. The key you hold might come from an earlier `GET /keys` response or from tooling that pins the key.
189189
190190| Key hash | SHA-256 fingerprint | Algorithm | Signing since | Status |
191191| ---------- | ------------------------------------------------------------------ | ------------------- | ------------- | ------------------- |
from line 208
208208curl --fail-with-body -sS -G \
209209 "https://api.anthropic.com/v1/compliance/transparency_log/inclusion" \
210210 --data-urlencode "leaf_index=41" \
211 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
212 --header "anthropic-version: 2023-06-01"
211 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
212 -H "anthropic-version: 2023-06-01"
213213```
214214
215215```json
from line 254
254254curl --fail-with-body -sS -G \
255255 "https://api.anthropic.com/v1/compliance/transparency_log/consistency" \
256256 --data-urlencode "from=1180" \
257 --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
258 --header "anthropic-version: 2023-06-01"
257 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
258 -H "anthropic-version: 2023-06-01"
259259```
260260
261261```json
from line 286
286286
287287`GET /v1/compliance/transparency_log/tile/{level}/{index}`
288288
289Returns `application/octet-stream`: concatenated 32-byte SHA-256 hashes, per tlog-tiles. Tile addressing follows tlog-tiles exactly, including the `{level}` and `{index}` path grammar, the `x001/234` index form for large trees, and the partial-tile suffix `.p/{width}`. Hash tiles are the unit from which tlog-tiles clients compute proofs themselves.
289Returns `application/octet-stream`: concatenated 32-byte SHA-256 hashes, as tlog-tiles specifies. Tile addressing follows tlog-tiles exactly, including the `{level}` and `{index}` path grammar, the `x001/234` index form for large trees, and the partial-tile suffix `.p/{width}`. Hash tiles are the unit from which tlog-tiles clients compute proofs themselves.
290290
291291* Full tiles are immutable and are served with `Cache-Control: private, max-age=604800, immutable`.
292292* Partial tiles are superseded as the tree grows and are served with `Cache-Control: private, no-store`. Once a tile fills, a request for its earlier partial form can return `404` even though the full tile exists. Falling back from the partial tile to the full tile is the client's job, as tlog-tiles specifies, and standard clients already do it.
from line 296
296296
297297`GET /v1/compliance/transparency_log/tile/entries/{index}`
298298
299Returns `application/octet-stream`: consecutive leaf entries, each prefixed with its big-endian `uint16` length, per tlog-tiles. Entry bundles contain event plaintext: the [canonical bytes](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#how-an-event-becomes-a-leaf) of each Access Transparency event. That is why the whole surface requires the Activity Feed's scope. Addressing, the partial form, caching, and errors are identical to hash tiles.
299Returns `application/octet-stream`: consecutive leaf entries, each prefixed with its big-endian `uint16` length, as tlog-tiles specifies. Entry bundles contain event plaintext: the [canonical bytes](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#how-an-event-becomes-a-leaf) of each Access Transparency event. That is why the whole surface requires the Activity Feed's scope. Addressing, the partial form, caching, and errors are identical to hash tiles.
300300
301301## The `transparency_log_leaf_index` field on Activity Feed events
302302
from line 303
303303`anthropic_access` and `cmek_preserve` events on `GET /v1/compliance/activities` carry `transparency_log_leaf_index`, an integer, whenever the event has a leaf. Other activity types never carry it.
304304
305305* **The key is absent, not `null`, when the event has no leaf.** A robust verifier treats an absent key and a `null` value the same way.
306* **An event is served without `transparency_log_leaf_index` in only two cases.** The first is while your organization is not enrolled in Access Transparency, that is, before enrollment or between an un-enrollment and a re-enrollment. The second is when the event was recorded before your organization's log was created. For an organization enrolled before the transparency log was introduced, that includes its earlier history. Once your log exists and while you are enrolled, every event is appended to the log before the feed serves it. If a fault prevents the feed from learning the index, the feed delays the event rather than serving it without one. The event is not lost: it is already in the log and appears on the feed, index included, once the fault is remediated. An index-less event is not expected when it is dated after your log was created and falls inside a period when you were enrolled.
306* **An event is served without `transparency_log_leaf_index` in only two cases.** The first is while your organization is not enrolled in Access Transparency, that is, before enrollment or between an un-enrollment and a re-enrollment. The second is when the event was recorded before your organization's log was created. For an organization enrolled before the transparency log was introduced, that includes its earlier history. Once your log exists and while you are enrolled, every event is appended to the log before the feed serves it. If a fault prevents the feed from obtaining the index, the feed delays the event rather than serving it without one. The event is not lost: it is already in the log and appears on the feed, index included, once the fault is remediated. An index-less event is not expected when it is dated after your log was created and falls inside a period when you were enrolled.
307307* **A present index is a pointer, not a proof.** Verify inclusion before treating the event as committed in the log. The anomaly worth escalating is a present index whose inclusion proof still cannot be fetched long after a covering checkpoint should have been published.
308308* The index is assigned when the event is appended to the log and is not one of the fields that make up the leaf.
309309
from line 393
393393
394394Each `run` fetches the latest checkpoint and verifies its signature and origin line. It then proves the log is an append-only extension of the checkpoint the previous run saved. Next it pages through the Access Transparency events on your Activity Feed. It starts seven days (by `created_at`) before the newest event the previous run read, so that events listed late or out of order are still picked up. It rebuilds each event's leaf, verifies an inclusion proof for it, and compares any event it verified before against what it recorded then. Finally, it saves the new checkpoint and its progress to the `--state` file, which the next run starts from. Run it at least daily. Hourly is reasonable. With a parent-organization key, run one copy per child organization, each with its own `--org` and `--state` file. Each child organization's UUID also comes from the Claude Console, not from the Compliance API responses you are verifying. To find it, switch to the child organization in the account menu at the bottom of the Console sidebar, then open the [Organization](https://platform.claude.com/settings/organization) page (`platform.claude.com/settings/organization`). You can also find it in your parent organization's list of organizations in the Console. `axt-verify checkpoint` does only the checkpoint and append-only steps. `axt-verify events FILE` verifies events you already hold, such as an auditor's sample or your own export. It proves that each event in the file is still committed in the log under the current checkpoint. It does not read the feed or touch the state file.
395395
396One limit follows from that window: `run` re-reads only the last seven days of events, so it re-checks recently served events (step 7), not your whole history. Keep the events you export (see [Keep your own checkpoint archive](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#keep-your-own-checkpoint-archive)). `axt-verify events FILE` proves at any later date that those copies are still committed in the log, but it does not re-read the feed. To detect an older event removed from or rewritten on the feed, re-export that range from the Activity Feed and compare it with the copies you kept. You can also verify the re-export itself with `axt-verify events FILE`. The seven-day overlap is longer than the feed's two-business-day delivery time, so a late-arriving event still falls inside a later run's window. `--overlap` changes the duration if you need to.
396One limit follows from that window: `run` re-reads only the last 7 days of events, so it re-checks recently served events (step 7), not your whole history. Keep the events you export (see [Keep your own checkpoint archive](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#keep-your-own-checkpoint-archive)). `axt-verify events FILE` proves at any later date that those copies are still committed in the log, but it does not re-read the feed. To detect an older event removed from or rewritten on the feed, re-export that range from the Activity Feed and compare it with the copies you kept. You can also verify the re-export itself with `axt-verify events FILE`. The 7-day overlap is longer than the feed's 2-business-day delivery time, so a late-arriving event still falls inside a later run's window. `--overlap` changes the duration if you need to.
397397
398398If you need your own implementation instead, follow the preceding checklist with a tlog-tiles library that supports ECDSA note keys.
399399
400400### Interpret the result
401401
402`axt-verify` prints your origin, the tree size and root hash of the checkpoint it verified, the tree size the append-only check started from, and a count of events by outcome. Pass `--json` to get the same report as one JSON object per line. Each event has one of four outcomes:
402`axt-verify` prints your origin, the tree size and root hash of the checkpoint it verified, the tree size the append-only check started from, and a count of events by outcome. Pass `--json` to get the same report as one JSON object on each line. Each event has one of four outcomes:
403403
404404* **Verified:** the leaf rebuilt from the served event is committed at the event's index in the signed log.
405405* **Pending:** the event's index is beyond the latest published checkpoint. This is normal for a short time after an event appears. In `run`, `axt-verify` remembers the event, verifies it on a later run once a checkpoint covers it, and fails it if that takes longer than 24 hours. `events FILE` has no later run to settle it, so it waits up to a minute for a covering checkpoint to be published. If none arrives, it reports the event as not yet covered and ends with exit status `3`. Run it again later. If `events FILE` reports the same event as not yet covered on two runs at least a day apart, treat it as a verification failure and escalate as for exit status `1`.
from line 406
406406* **Not logged:** the event was served without an index. An event is served without `transparency_log_leaf_index` only while your organization is not enrolled in Access Transparency, or when it was recorded before your organization's log was created (see [The `transparency_log_leaf_index` field on Activity Feed events](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#the-transparency-log-leaf-index-field-on-activity-feed-events)). `axt-verify` reports such events as not logged and does not fail the run on them. An index-less event is not expected when it is dated after your log was created and falls inside a period when you were enrolled. Review the not-logged list in the run's summary or `--json` output rather than relying on the exit status alone.
407407* **Failed:** see exit status `1`.
408408
409The exit status tells your scheduler what happened:
409The exit status tells your scheduler what occurred:
410410
411411* **`0`:** Nothing failed. Not-logged events are reported, not failed, and so are pending events in `run`.
412412
from line 422
422422 * An event still pending 24 hours after the run first saw it.
423423 * A refused inclusion proof (`400`, `401`, or `403`) for an event the feed served you.
424424 * An inclusion proof returned for a different `leaf_index` from the one requested.
425 * In `events FILE`, an event at an index the latest checkpoint already covered when the check began, for which no inclusion proof is served before the wait runs out.
425 * In `events FILE`, an event at an index the latest checkpoint already covered when the check started, for which no inclusion proof is served before the wait runs out.
426426 * An event whose `organization_uuid` is not the organization UUID you passed with `--org`. When a parent organization runs `events FILE` on an export that covers several child organizations, every other organization's event fails this way, so split the export by organization first and verify each part with its own `--org`.
427427 * The same activity `id` at two different indices, or twice at one index with different content, within one run or one `events FILE` input.
428428 * An event whose leaf cannot be rebuilt: for example, a documented field that is not a string, a field name that appears twice, or a `type` that is missing or is an unrecognized variant of an Access Transparency type. `events FILE` skips rows of other activity types and does not fail them.
from line 441
441441 * An unexpected response.
442442 * A state or `--save` file that could not be written.
443443
444 An exit status `3` with `404` responses is expected until Anthropic has recorded a first Access Transparency event for your organization, because every transparency log endpoint returns `404` until that event creates the log. Escalate if the transparency log endpoints still return `404` more than a few days after your Activity Feed first shows an Access Transparency event, whether or not that event carries a `transparency_log_leaf_index`. That combination is not expected. Once a run has succeeded, escalate an exit status `3` that persists.
444 An exit status `3` with `404` responses is expected until Anthropic has recorded a first Access Transparency event for your organization, because every transparency log endpoint returns `404` until that event creates the log. Escalate if the transparency log endpoints still return `404` more than a few days after your Activity Feed first shows an Access Transparency event, regardless of whether that event carries a `transparency_log_leaf_index`. That combination is not expected. Once a run has succeeded, escalate an exit status `3` that persists.
445445
446446### Keep your own checkpoint archive
447447
from line 471
471471 </Accordion>
472472
473473 <Accordion title="Can I verify all of my child organizations with one key?">
474 Yes. A parent-organization key reads any enrolled child organization's log by passing `organization_id`. Each child organization has its own log, origin, and saved checkpoint. Run one verification per child organization, each with its own state.
474 Yes. A parent-organization key reads any enrolled child organization's log by passing `organization_id`. Each child organization has its own log, origin, and saved checkpoint. Run a separate verification, with its own state, for each child organization.
475475 </Accordion>
476476</AccordionGroup>
477477
from line 480
480480* [Access Transparency](https://platform.claude.com/docs/en/manage-claude/access-transparency)
481481* [Query the Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed)
482482* [Compliance API overview](https://platform.claude.com/docs/en/manage-claude/compliance-api)
483* [Errors](https://platform.claude.com/docs/en/manage-claude/compliance-errors)
483* [Handle Compliance API errors](https://platform.claude.com/docs/en/manage-claude/compliance-errors)
484484* [axt-verify](https://github.com/anthropics/axt-verify), Anthropic's open-source verifier for the transparency log
485485* [C2SP tlog-tiles](https://c2sp.org/tlog-tiles) and [C2SP signed note](https://c2sp.org/signed-note), the wire formats for tiles, entry bundles, and checkpoints
486486* [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162), the Merkle tree, inclusion proof, and consistency proof algorithms
manage-claude/admin-api Changed · +6 / -6 lines
from line 30
3030
3131An Admin API key covers most endpoints. The service-account, federation-issuer, and federation-rule endpoints accept only an `org:admin` OAuth token. Send a personal key or service account key in the `x-api-key` header, as you would an Admin API key. The following examples call the [organization info endpoint](https://platform.claude.com/docs/en/manage-claude/admin-api#accessing-organization-info) with an OAuth token and with an Admin API key.
3232
33The Python, TypeScript, C#, Go, Java, PHP, and Ruby SDKs expose the endpoints on this page under `client.organization` (csharp, go: `client.Organization`; java: `client.organization()`; php: `$client->organization`), and the `ant` CLI under `ant organization`. The examples on this page use the default client, which reads an Admin API key from `ANTHROPIC_API_KEY` or an OAuth bearer token from `ANTHROPIC_AUTH_TOKEN`. SDK list methods in Python, TypeScript, C#, Go, and Java return an iterator that fetches more pages on demand, so `limit` sets the page size, not the total. The PHP, Ruby, and curl examples return one page. In the CLI, `--limit` caps the results on the member, invite, workspace, workspace-member, and API-key lists. For each endpoint's parameters and responses, see the [Admin API reference](https://platform.claude.com/docs/en/api/organization).
33The SDK exposes the endpoints on this page under `client.organization` (csharp, go: `client.Organization`; java: `client.organization()`; php: `$client->organization`), and the `ant` CLI under `ant organization`. The examples on this page use the default client, which reads an Admin API key from `ANTHROPIC_API_KEY` or an OAuth bearer token from `ANTHROPIC_AUTH_TOKEN`. SDK list methods in Python, TypeScript, C#, Go, and Java return an iterator that fetches more pages on demand, so `limit` sets the page size, not the total. The PHP, Ruby, and curl examples return one page. In the CLI, `--limit` caps the results on the member, invite, workspace, workspace-member, and API-key lists. For each endpoint's parameters and responses, see the [Admin API reference](https://platform.claude.com/docs/en/api/organization).
3434
3535### OAuth bearer token
3636
from line 43
4343
4444Interactive tokens are short-lived. If requests start returning 401, re-run the `export` command to refresh the token.
4545
46The SDKs and the `ant` CLI read `ANTHROPIC_AUTH_TOKEN` automatically. Leave `ANTHROPIC_API_KEY` unset in the same shell so they send the bearer token. Automated workloads skip the login: they authenticate through workload identity federation, and the SDKs and CLI perform the token exchange from the federation environment variables. See [Bootstrap a workload to manage WIF](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#bootstrap-a-workload-to-manage-wif).
46The SDK and the `ant` CLI read `ANTHROPIC_AUTH_TOKEN` automatically. Leave `ANTHROPIC_API_KEY` unset in the same shell so they send the bearer token. Automated workloads skip the login: they authenticate through workload identity federation, and the SDK and CLI perform the token exchange from the federation environment variables. See [Bootstrap a workload to manage WIF](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#bootstrap-a-workload-to-manage-wif).
4747
4848Call the Admin API with the exported token:
4949
from line 1342
13421342
13431343### API keys
13441344
1345Monitor and manage [API keys](https://platform.claude.com/docs/en/api/organization/api_keys/list). Each key in the response includes its `expires_at` timestamp (`null` for keys without an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration)) and `principal`, the identity it acts as (see [Key types](https://platform.claude.com/docs/en/manage-claude/authentication#key-types)). For a personal key, `principal` is `{"type": "user_actor", "user_id": "user_..."}`; for a service account key, `{"type": "service_account_actor", "service_account_id": "svac_..."}`; and for a workspace key, `null`. Each key also has a `scope` object: `{"type": "workspace", "workspace_id": "wrkspc_..."}` for a key bound to one workspace, or `{"type": "organization"}` for a key that can work across any workspace the account has access to. Filtering the list by `workspace_id` with the Default Workspace's ID returns only keys bound to the Default Workspace; keys without a workspace scope aren't returned under any `workspace_id` filter.
1345Monitor and manage [API keys](https://platform.claude.com/docs/en/api/organization/api_keys/list). Each key in the response includes its `expires_at` timestamp (`null` for keys without an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration)) and `principal`, the identity it acts as (see [Key types](https://platform.claude.com/docs/en/manage-claude/authentication#key-types)). For a personal key, `principal` is `{"type": "user_actor", "user_id": "user_..."}`. For a service account key, it is `{"type": "service_account_actor", "service_account_id": "svac_..."}`. For a workspace key, it is `null`. Each key also has a `scope` object: `{"type": "workspace", "workspace_id": "wrkspc_..."}` for a key bound to one workspace, or `{"type": "organization"}` for a key that can work across any workspace the account has access to. Filtering the list by `workspace_id` with the Default Workspace's ID returns only keys bound to the Default Workspace; keys without a workspace scope aren't returned under any `workspace_id` filter.
13461346
13471347List the active API keys in a workspace:
13481348
from line 1612
16121612
16131613### Service accounts
16141614
1615Create and manage service accounts (`svac_...`), the non-human identities that [service account keys](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) and [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) tokens act as. These endpoints, like the federation-issuer and federation-rule endpoints, require an `org:admin` OAuth token. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#service-accounts).
1615Create and manage service accounts (`svac_...`), the non-human identities that [service account keys](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) and [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) tokens act as. These endpoints, like the federation-issuer and federation-rule endpoints, require an `org:admin` OAuth token. See [Service accounts in Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#service-accounts).
16161616
16171617### Federation issuers
16181618
1619Register the OIDC identity providers (`fdis_...`) whose tokens may assert workload identity for your organization. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#federation-issuers).
1619Register the OIDC identity providers (`fdis_...`) whose tokens may assert workload identity for your organization. See [Federation issuers in Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#federation-issuers).
16201620
16211621### Federation rules
16221622
1623Manage the rules (`fdrl_...`) that map issuer tokens to service accounts and scopes. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#federation-rules).
1623Manage the rules (`fdrl_...`) that map issuer tokens to service accounts and scopes. See [Federation rules in Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api#federation-rules).
16241624
16251625## Accessing organization info
16261626
manage-claude/admin-api-keys Changed · +4 / -4 lines
from line 29
2929 </Step>
3030
3131 <Step title="Create the key">
32 Click **Create admin key**, give it a name, choose a [key expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration), and click **Add**. Claude Console keys do not have selectable scopes; every key carries full access to all endpoints that accept Admin API keys (the service-account and federation endpoints noted at the top of this page do not accept Admin API keys).
32 Click **Create admin key**, give it a name, select a [key expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration), and click **Add**. Claude Console keys do not have selectable scopes; every key carries full access to all endpoints that accept Admin API keys (the service-account and federation endpoints noted at the top of this page do not accept Admin API keys).
3333 </Step>
3434
3535 <Step title="Copy and store the secret">
from line 64
6464| To call... | Select these scopes |
6565| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
6666| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management): list and look up members and invites; read custom roles and their permissions | `read:members` |
67| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management): change member roles, remove members, create and withdraw invites (to assign the `managed` role on a role change or an invite, also select `write:rbac_groups`) | `write:members` |
67| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management): change member roles, remove members, and create and withdraw invites (to assign the `managed` role on a role change or an invite, also select `write:rbac_groups`) | `write:members` |
6868| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management): read groups and their members | `read:rbac_groups` |
6969| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management): create, rename, and delete groups; add and remove group members; with `write:members`, assign the `managed` role (on an invite or a role change) or assign groups on an invite | `write:rbac_groups` |
7070| [Plugins API](https://platform.claude.com/docs/en/manage-claude/plugins-api): read plugins, versions, installation settings, shares, and marketplaces; download plugin files, including the files of members' personal plugins; validate a marketplace before you connect it | `read:plugins` |
from line 75
7575| [Compliance API Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed): organization-wide activity events | `read:compliance_activities` |
7676| [Compliance API chat, file, and project endpoints](https://platform.claude.com/docs/en/manage-claude/compliance-content-data) and [Compliance API session endpoints](https://platform.claude.com/docs/en/manage-claude/compliance-sessions): read chats, files, projects, session transcripts, and [organization users](https://platform.claude.com/docs/en/manage-claude/compliance-org-data#list-organization-users) | `read:compliance_user_data` |
7777| [Compliance API chat, file, and project endpoints](https://platform.claude.com/docs/en/manage-claude/compliance-content-data): delete chats, files, and projects | `delete:compliance_user_data` |
78| [Compliance API organization endpoints](https://platform.claude.com/docs/en/manage-claude/compliance-org-data): read organization metadata and effective settings | `read:compliance_org_data` |
79| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management) read endpoints and every Compliance API read endpoint, with a single read-only scope (for security-audit integrations; does not include the Spend Limits or Analytics APIs) | `read:org_audit` |
78| [Compliance API organization endpoints](https://platform.claude.com/docs/en/manage-claude/compliance-org-data): read organization metadata and effective settings; [Plugins API](https://platform.claude.com/docs/en/manage-claude/plugins-api): every `GET` endpoint, including file downloads | `read:compliance_org_data` |
79| Admin API [user management](https://platform.claude.com/docs/en/manage-claude/user-management) read endpoints, every Compliance API read endpoint, and every [Plugins API](https://platform.claude.com/docs/en/manage-claude/plugins-api) `GET` endpoint, including file downloads, with a single read-only scope (for security-audit integrations; does not include the Spend Limits or Analytics APIs) | `read:org_audit` |
8080
8181The Compliance and Analytics APIs must be enabled for your organization before keys with those scopes can be used. See [Set up the Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api-access#set-up-the-compliance-api) and [Get access to the Claude Enterprise Analytics API](https://platform.claude.com/docs/en/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api).
8282
manage-claude/analytics-api Changed · +8 / -8 lines
from line 46
4646
4747 ```bash
4848 curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2025-09-08" \
49 --header "anthropic-version: 2023-06-01" \
50 --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
49 -H "anthropic-version: 2023-06-01" \
50 -H "x-api-key: $ANTHROPIC_ADMIN_KEY"
5151 ```
5252 </Step>
5353</Steps>
5454
55For the available metrics, request parameters, and response schema, see the [Claude Code Analytics API guide](https://platform.claude.com/docs/en/manage-claude/claude-code-analytics-api) and the [API reference](https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_claude_code).
55For the available metrics, request parameters, and response schema, see the [Claude Code Analytics API](https://platform.claude.com/docs/en/manage-claude/claude-code-analytics-api) guide and the [API reference](https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_claude_code).
5656
5757## Get access to the Claude Enterprise Analytics API
5858
from line 85
8585
8686Claude Enterprise Analytics API data is available for dates on or after January 1, 2026.
8787
88**Engagement and adoption endpoints** (user activity, summaries, projects, skills, connectors) return a per-day snapshot for the date you specify. Data for a given day is typically available by about 13:00–13:30 UTC the following day (a 1-day lag); until then, the most recent available day is usually two days before the current UTC date. Data arrives later on days when an upstream data pipeline runs late, and exact freshness varies by query, so rather than assuming a fixed time, check the error response: requesting a date that is not yet available returns a 400 error naming the most recent available day. If data is not available well past the typical lag, it usually indicates a data pipeline failure on Anthropic's side; contact support if the gap persists.
88**Engagement and adoption endpoints** (user activity, summaries, projects, skills, connectors) return a per-day snapshot for the date you specify. Data for a given day is typically available by about 13:00–13:30 UTC the following day (a 1-day lag); until then, the most recent available day is usually 2 days before the current UTC date. Data arrives later on days when an upstream data pipeline runs late, and exact freshness varies by query, so rather than assuming a fixed time, check the error response: requesting a date that is not yet available returns a 400 error naming the most recent available day. If data is not available well past the typical lag, it usually indicates a data pipeline failure on Anthropic's side; contact support if the gap persists.
8989
90**Cost and usage endpoints** follow a different freshness model. Data is typically available within four hours of the underlying usage but may take up to 24 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month. For example, values for October 1 can change until about November 7. For invoicing-grade totals, query only months that ended at least 7 days ago.
90**Cost and usage endpoints** follow a different freshness model. Data is typically available within 4 hours of the underlying usage but might take up to 24 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month. For example, values for October 1 can change until about November 7. For invoicing-grade totals, query only months that ended at least 7 days ago.
9191
9292<Note>
9393 Cost and usage responses include a `data_refreshed_at` timestamp. When `ending_at` is omitted (the default is the current time), the response includes a tail of data after `data_refreshed_at` that is incomplete. For stable results across repeated calls, set `ending_at` to a value at or before a previously returned `data_refreshed_at`.
from line 105
105105
106106Some activity from users of Chat and Cowork unified, such as voice mode, can still be reported under chat or Cowork. A user's activity can also be split between products on the day they start using Chat and Cowork unified. The same is true on the day it is turned off for them. How the activity splits is not guaranteed.
107107
108A user can appear in both the chat or Cowork counts and the Chat and Cowork unified counts. This can happen on a day when they use Chat and Cowork unified and some of their activity is still reported under chat or Cowork. Weekly and monthly counts can include them in both when the window has activity of both kinds, even on different days. For example, the window might cover days before and after they started using Chat and Cowork unified.
108A user can appear in both the chat or Cowork counts and the Chat and Cowork unified counts. This can occur on a day when they use Chat and Cowork unified and some of their activity is still reported under chat or Cowork. Weekly and monthly counts can include them in both when the window has activity of both kinds, even on different days. For example, the window might cover days before and after they started using Chat and Cowork unified.
109109
110110When you filter user activity by project, each day's project activity is counted in one place only. If a user sent a chat message in Chat and Cowork unified that day, all their project activity is counted in `chat_cowork_unified_metrics.chat`. Otherwise, it is counted in `chat_metrics`.
111111
from line 119
119119
120120**List parameters use bracket notation.** Repeat the parameter for each value, for example `products[]=chat&products[]=claude_code`.
121121
122**Amount fields are decimal strings in cents.** Currency amounts are returned as decimal strings such as `"41280.000000"` (which represents $412.80). To convert to dollars, parse as a decimal and divide by 100. Avoid binary floating-point parsing for values that may exceed several million dollars.
122**Amount fields are decimal strings in cents.** Currency amounts are returned as decimal strings such as `"41280.000000"` (which represents $412.80 USD). To convert to dollars, parse as a decimal and divide by 100. Avoid binary floating-point parsing for values that might exceed several million dollars.
123123
124**Rate limits apply at the organization level**, not per key, with a default of 60 requests per minute across all endpoints in this API. If that is not sufficient for your use case, contact your Anthropic account team to discuss adjusting the limit.
124**Rate limits apply at the organization level**, not for each key, with a default of 60 requests per minute across all endpoints in this API. If that is not sufficient for your use case, contact your Anthropic account team to discuss adjusting the limit.
125125
126126## Versioning
127127
manage-claude/api-and-data-retention Changed · +41 / -41 lines
from line 10
1010
1111## How Anthropic approaches data retention
1212
13Different APIs and features have different storage needs. Where a feature does not require storage of customer prompts or responses, it may be eligible for ZDR. Where a feature necessarily requires storage, Anthropic designs for the smallest possible retention footprint under the following commitments:
13Different APIs and features have different storage needs. Where a feature does not require storage of customer prompts or responses, it might be eligible for ZDR. Where a feature necessarily requires storage, Anthropic designs for the smallest possible retention footprint under the following commitments:
1414
1515* Retained data is never used for model training without your express permission.
1616* Only what is technically necessary for the feature to work is retained. Conversation content (your prompts and Claude's outputs) is not retained by default; the exception is [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements), which require 30-day retention.
from line 24
2424
2525### What ZDR covers
2626
27* **Claude Messages and Token Counting APIs:** ZDR applies to these endpoints for eligible features listed in the [feature eligibility table](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility). Features that ride on `/v1/messages` but are marked "No" in the table (such as code execution) are not covered.
27* **Claude Messages and Token Counting APIs:** ZDR applies to these endpoints for eligible features listed in the [feature eligibility table](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility). Features that use `/v1/messages` but are marked "No" in the table (such as code execution) are not covered.
2828* **Claude Code with API keys:** ZDR applies when Claude Code is used with API keys from a Commercial organization (an organization under Anthropic's Commercial Terms of Service, as distinct from a consumer Claude account). If metrics logging is enabled in Claude Code, productivity data such as usage statistics is exempted from ZDR and may be retained. Claude Code on Claude Enterprise is not covered by this arrangement and has a separate ZDR offering; see [What ZDR does not cover](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#what-zdr-does-not-cover).
2929* **Claude Platform on AWS:** [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) follows the same data retention policy as the first-party Claude API. ZDR is available on request; contact your Anthropic account representative to enable it.
3030
from line 165
165165* **Yes (qualified):** Your prompts and Claude's outputs are not stored, but a bounded technical artifact (named in the Details column) is retained briefly for the feature to function. See [How Anthropic approaches data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#how-anthropic-approaches-data-retention) for the commitments that govern these features.
166166* **No:** The feature is not eligible. Under HIPAA readiness, the API blocks requests that include a "No" feature and returns a `400` error, unless the feature's Details column says otherwise. Under ZDR, the API does **not** block these features; using one is a choice to step outside your ZDR arrangement for that specific data, and the feature's own documented retention policy applies. Features marked "No" for ZDR are typically stateful (they store jobs, files, or container state), which is why they cannot be zero-retention.
167167
168| Feature | Endpoint | ZDR eligible | HIPAA eligible | Details |
169| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170| [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
171| [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
172| [Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | `/v1/messages`<br />with `advisor` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Advisor model output is returned in the API response; nothing is stored server-side after the response. |
173| [Agent skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | `/v1/skills`<br />`/v1/messages` with `skills` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Skill data retained per standard policy. See [Agent skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#data-retention). |
174| [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) | `/v1/messages`<br />with `bash` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool executed in your environment. |
175| [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | `/v1/messages/batches` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | 29-day retention; async storage required. See [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing#data-retention). |
176| [Browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | `/v1/messages`<br />with `browser` toolset | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Client-side tool. Anthropic does not run browser actions or retain page content beyond standard API handling. Not covered under HIPAA readiness; requests that include the browser use tool are not blocked. See [Browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#data-retention). |
177| [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) | `/v1/messages`<br />with `diagnostics` | <Eligible status="qualified">Yes (qualified)</Eligible> | <Eligible status="no">No</Eligible> | Your prompts and Claude's outputs are not stored. A fingerprint of cryptographic hashes and token-count estimates is retained briefly to enable comparison against the next request. See [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#data-retention). |
178| [Citations](https://platform.claude.com/docs/en/build-with-claude/citations) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
179| [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) | `/v1/agents`<br />`/v1/sessions`<br />`/v1/environments` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Sessions are stateful resources; transcripts persist until you delete them. Applies to all Managed Agents sub-features, including [Self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes). |
180| [Code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) | `/v1/messages`<br />with `code_execution` tool | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Container data retained up to 30 days. See [Code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#data-retention). |
181| [Computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) | `/v1/messages`<br />with `computer` toolset or tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool where screenshots and files are captured and stored in your environment, not by Anthropic. See [Computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#data-retention). |
182| [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) | `/v1/messages`<br />with `context_management` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Context edits (tool use clearing and thinking clearing) are applied in real time. |
183| [Context management (compaction)](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) | `/v1/messages`<br />with `context_management` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side compaction results are returned and round-tripped statelessly through the API response. |
184| [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) | `/v1/messages`<br />with `inference_geo` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
185| [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) | `/v1/messages`<br />with `effort` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
186| [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) | `/v1/messages`<br />with `speed: "fast"` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Same Messages API endpoint with faster inference. ZDR applies regardless of speed setting. |
187| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | `/v1/files` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Files retained until explicitly deleted or they reach their configured expiration. See [Files API](https://platform.claude.com/docs/en/build-with-claude/files#data-retention). |
188| [Fine-grained tool streaming](https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
189| [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) | `/v1/messages`<br />with `mcp_servers` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Data retained per standard policy. See [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#data-retention). |
190| [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) | `/v1/tunnels` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Research preview. See [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) for the data-flow boundary and subprocessor details. |
191| [Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) | `/v1/messages`<br />with `memory` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side memory storage where you control data retention. |
192| [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Standard API calls for generating Claude responses. |
193| [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) | `/v1/messages`<br />with `role: "system"` messages | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Request-shape capability of the Messages API; mid-conversation system messages flow through the standard inference path and nothing is stored server-side after the response. |
194| [OpenTelemetry export](https://platform.claude.com/docs/en/manage-claude/opentelemetry) | `/v1/organizations/telemetry_destinations` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Beta. Spans have the same ZDR eligibility as the feature that produces them. HIPAA organizations can export metadata. SDK spans go directly from your environment to your exporter. After delivery, the data is held by the service that you chose, outside Anthropic, under that service's retention and access controls. |
195| [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | HIPAA eligibility applies to PDFs sent inline through the Messages API, not through the Files API. |
196| [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | `/v1/messages`<br />with `code_execution` tool | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Built on code execution containers; data retained up to 30 days. See [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#data-retention). |
197| [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Your prompts and Claude's outputs are not stored. KV cache representations and cryptographic hashes are held in memory for the cache TTL and promptly deleted after expiry. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#data-retention). |
198| [Search results](https://platform.claude.com/docs/en/build-with-claude/search-results) | `/v1/messages`<br />with `search_results` source | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
199| [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `/v1/messages` | <Eligible status="qualified">Yes (qualified)</Eligible> | <Eligible>Yes</Eligible> | Your prompts and Claude's outputs are not stored. Only the JSON schema is cached, for up to 24 hours since last use. This also covers [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) (`strict: true` on tools), which uses the same grammar pipeline. PHI must not be included in JSON schema definitions; see [PHI handling guidelines](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#phi-handling-guidelines). See [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#data-retention). |
200| [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool) | `/v1/messages`<br />with `text_editor` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool executed in your environment. |
201| [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) | `/v1/messages`<br />with `thinking` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
202| [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) | `/v1/messages/count_tokens` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Count tokens before sending requests. |
203| [Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | `/v1/messages`<br />with `tool_search` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side tool executed by Anthropic; the tool definitions in the request are searched in memory per call and nothing is stored after the response. |
204| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | `/v1/user_profiles` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Profiles are metadata about your end customers and don't contain prompts or outputs. The profile data you send is retained per standard policy until you delete the profile. Not covered under HIPAA readiness; requests to `/v1/user_profiles` are not blocked. See [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles#what-a-profile-contains-and-how-anthropic-uses-it). |
205| [Web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `/v1/messages`<br />with `web_fetch` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Fetched web content returned in the API response. [Dynamic filtering](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. Website publishers may retain request data (such as fetched URLs and request metadata) according to their own policies. |
206| [Web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) | `/v1/messages`<br />with `web_search` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Real-time web search results returned in the API response. [Dynamic filtering](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. |
168| Feature | Endpoint | ZDR eligible | HIPAA eligible | Details |
169| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170| [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
171| [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
172| [Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | `/v1/messages`<br />with `advisor` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Advisor model output is returned in the API response; nothing is stored server-side after the response. |
173| [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | `/v1/skills`<br />`/v1/messages` with `skills` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Skill data retained per standard policy. See [Agent Skills data retention](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#data-retention). |
174| [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) | `/v1/messages`<br />with `bash` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool run in your environment. |
175| [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | `/v1/messages/batches` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | 29-day retention; async storage required. See [Batch processing data retention](https://platform.claude.com/docs/en/build-with-claude/batch-processing#data-retention). |
176| [Browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | `/v1/messages`<br />with `browser` toolset | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Client-side tool. Anthropic does not run browser actions or retain page content beyond standard API handling. Not covered under HIPAA readiness; requests that include the browser use tool are not blocked. See [Browser use data retention](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#data-retention). |
177| [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) | `/v1/messages`<br />with `diagnostics` | <Eligible status="qualified">Yes (qualified)</Eligible> | <Eligible status="no">No</Eligible> | Your prompts and Claude's outputs are not stored. A fingerprint of cryptographic hashes and token-count estimates is retained briefly to allow comparison against the next request. See [Cache diagnostics data retention](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#data-retention). |
178| [Citations](https://platform.claude.com/docs/en/build-with-claude/citations) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
179| [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) | `/v1/agents`<br />`/v1/sessions`<br />`/v1/environments` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Sessions are stateful resources; transcripts persist until you delete them. Applies to all Managed Agents sub-features, including [Self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes). |
180| [Code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) | `/v1/messages`<br />with `code_execution` tool | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Container data retained up to 30 days. See [Code execution data retention](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#data-retention). |
181| [Computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) | `/v1/messages`<br />with `computer` toolset or tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool where screenshots and files are captured and stored in your environment, not by Anthropic. See [Computer use data retention](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#data-retention). |
182| [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) | `/v1/messages`<br />with `context_management` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Context edits (tool use clearing and thinking clearing) are applied in real time. |
183| [Context management (compaction)](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) | `/v1/messages`<br />with `context_management` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side compaction results are returned and round-tripped statelessly through the API response. |
184| [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) | `/v1/messages`<br />with `inference_geo` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
185| [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) | `/v1/messages`<br />with `effort` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
186| [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) | `/v1/messages`<br />with `speed: "fast"` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Same Messages API endpoint with faster inference. ZDR applies regardless of speed setting. |
187| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | `/v1/files` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Files retained until explicitly deleted or they reach their configured expiration. See [Files API file lifecycle](https://platform.claude.com/docs/en/build-with-claude/files#data-retention). |
188| [Fine-grained tool streaming](https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
189| [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) | `/v1/messages`<br />with `mcp_servers` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Data retained per standard policy. See [MCP connector data retention](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#data-retention). |
190| [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) | `/v1/tunnels` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Research preview. See [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) for the data-flow boundary and subprocessor details. |
191| [Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) | `/v1/messages`<br />with `memory` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side memory storage where you control data retention. |
192| [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Standard API calls for generating Claude responses. |
193| [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) | `/v1/messages`<br />with `role: "system"` messages | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Request-shape capability of the Messages API; mid-conversation system messages flow through the standard inference path and nothing is stored server-side after the response. |
194| [OpenTelemetry export](https://platform.claude.com/docs/en/manage-claude/opentelemetry) | `/v1/organizations/telemetry_destinations` | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Beta. Spans have the same ZDR eligibility as the feature that produces them. HIPAA organizations can export metadata. SDK spans go directly from your environment to your exporter. After delivery, the data is held by the service that you chose, outside Anthropic, under that service's retention and access controls. |
195| [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | HIPAA eligibility applies to PDFs sent inline through the Messages API, not through the Files API. |
196| [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | `/v1/messages`<br />with `code_execution` tool | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Built on code execution containers; data retained up to 30 days. See [Programmatic tool calling data retention](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#data-retention). |
197| [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Your prompts and Claude's outputs are not stored. KV cache representations and cryptographic hashes are held in memory for the cache TTL and promptly deleted after expiry. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#data-retention). |
198| [Search results](https://platform.claude.com/docs/en/build-with-claude/search-results) | `/v1/messages`<br />with `search_results` source | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
199| [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `/v1/messages` | <Eligible status="qualified">Yes (qualified)</Eligible> | <Eligible>Yes</Eligible> | Your prompts and Claude's outputs are not stored. Only the JSON schema is cached, for up to 24 hours since last use. This also covers [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) (`strict: true` on tools), which uses the same grammar pipeline. PHI must not be included in JSON schema definitions; see [PHI handling guidelines](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#phi-handling-guidelines). See [Structured outputs data retention](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#data-retention). |
200| [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool) | `/v1/messages`<br />with `text_editor` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool run in your environment. |
201| [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) | `/v1/messages`<br />with `thinking` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | |
202| [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) | `/v1/messages/count_tokens` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Count tokens before sending requests. |
203| [Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | `/v1/messages`<br />with `tool_search` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side tool run by Anthropic; the tool definitions in the request are searched in memory per call and nothing is stored after the response. |
204| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | `/v1/user_profiles` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Profiles are metadata about your end customers and don't contain prompts or outputs. The profile data you send is retained per standard policy until you delete the profile. Not covered under HIPAA readiness; requests to `/v1/user_profiles` are not blocked. See [What a profile contains and how Anthropic uses it](https://platform.claude.com/docs/en/manage-claude/user-profiles#what-a-profile-contains-and-how-anthropic-uses-it). |
205| [Web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `/v1/messages`<br />with `web_fetch` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Fetched web content returned in the API response. [Dynamic filtering for web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. Website publishers might retain request data (such as fetched URLs and request metadata) according to their own policies. |
206| [Web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) | `/v1/messages`<br />with `web_search` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Real-time web search results returned in the API response. [Dynamic filtering for web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. |
207207
208208## Retention regardless of arrangement
209209
manage-claude/authentication Changed · +21 / -21 lines
from line 22
2222
2323When you create a key, you choose its type, which determines what the key can do, where it works, and when it stops working:
2424
25| Key type | Acts as | Works in | Stops working when |
26| -------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
27| **Personal key** | You, the user, with your roles and permissions | Either a single workspace or the workspaces where your role allows API use, chosen when the key is created | You lose access to the organization or, for a single-workspace key, to that workspace. Personal keys are archived when you are removed from the organization. If you are re-invited, create new keys; archived keys are not restored |
28| **Service account key** | A [service account](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#service-accounts) | Either a single workspace or anything the service account has access to, chosen when the key is created. A service account has access to the Default Workspace and to workspaces it has been added to | The service account is archived or, for a single-workspace key, is removed from that workspace |
29| **Workspace key** (legacy) | No one: it belongs to the workspace it was created in | That workspace | It expires, is disabled or deleted, or its workspace is archived, regardless of whether its creator leaves the organization |
25| Key type | Acts as | Works in | Stops working when |
26| -------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
27| **Personal key** | You, the user, with your roles and permissions | Either a single workspace or the workspaces where your role allows API use, chosen when the key is created | You lose access to the organization. A single-workspace key also stops working when you lose access to that workspace or that workspace is archived. Personal keys are archived when you are removed from the organization. If you are re-invited, create new keys; archived keys are not restored |
28| **Service account key** | A [service account](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#service-accounts) | Either a single workspace or anything the service account has access to, chosen when the key is created. A service account has access to the Default Workspace and to workspaces it has been added to | The service account is archived. A single-workspace key also stops working when the service account is removed from that workspace or that workspace is archived |
29| **Workspace key** (legacy) | No one: it belongs to the workspace it was created in | That workspace | It expires, is disabled or deleted, or its workspace is archived, regardless of whether its creator leaves the organization |
3030
31Personal keys and service account keys are identity-backed: each belongs to a user or service account your organization already manages, and every request acts as that identity. When that identity is removed from the organization, the key stops working. This means that keys won't accidentally outlive the people or workloads that own them. Prefer them over workspace keys for new integrations.
31Personal keys and service account keys are identity-backed: each belongs to a user or service account your organization already manages, and every request acts as that identity. When that identity is removed from the organization, the key stops working. This means that keys don't accidentally outlive the people or workloads that own them. Prefer them over workspace keys for new integrations.
3232
3333Use a personal key for your own development and scripts. A shared personal key acts as one person and breaks when they leave. For shared or automated workloads (CI, production services), have an organization admin create a service account so the workload has its own identity.
3434
from line 36
3636
3737### Create and use a key
3838
39* **Create a key:** In the Claude Console, go to the [API keys](https://platform.claude.com/settings/keys) page (`platform.claude.com/settings/keys`) and click **Create key**. Name the key and choose an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration). Set **Linked account** to yourself for a personal key, or to a service account for a key shared across multiple users. You can also scope the key to a specific workspace, which lets you skip setting a workspace ID manually in future requests.
40* **Use the key:** Send it as `Authorization: Bearer <key>` on direct HTTP requests, or set the `ANTHROPIC_API_KEY` environment variable and the [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) pick it up automatically.
39* **Create a key:** In the Claude Console, go to the [API keys](https://platform.claude.com/settings/keys) page (`platform.claude.com/settings/keys`) and click **Create key**. Name the key and select an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration). Set **Linked account** to yourself for a personal key, or to a service account for a key shared across multiple users. You can also scope the key to a specific workspace, which lets you skip setting a workspace ID manually in future requests.
40* **Use the key:** Send it as `Authorization: Bearer <key>` on direct HTTP requests, or set the `ANTHROPIC_API_KEY` environment variable and the [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) picks it up automatically.
4141
4242```http
4343POST /v1/messages
from line 63
6363 }'
6464 ```
6565
66 ```bash CLI
67 # See /docs/en/cli-sdks-libraries/cli/authentication#api-key for zsh, bash, and Windows variants
68 export ANTHROPIC_API_KEY=sk-ant-api03-...
69 ```
70
6671 ```python Python
6772 client = Anthropic(api_key="my-anthropic-api-key")
6873 # or, with ANTHROPIC_API_KEY set in the environment:
from line 119
114119 # or, with ANTHROPIC_API_KEY set in the environment:
115120 anthropic = Anthropic::Client.new
116121 ```
117
118 ```bash CLI
119 # See /docs/en/cli-sdks-libraries/cli/authentication#api-key for zsh, bash, and Windows variants
120 export ANTHROPIC_API_KEY=sk-ant-api03-...
121 ```
122122</CodeGroup>
123123
124124### Select a workspace
from line 125
125125
126126API keys that are created for a specific workspace only work in that workspace, and API requests using these keys can omit the workspace ID.
127127
128If your API key isn't scoped to a workspace, you must specify the workspace ID in the `anthropic-workspace-id` header for each request. See the following example for how to set this header in a request or in SDKs.
128If your API key isn't scoped to a workspace, you must specify the workspace ID in the `anthropic-workspace-id` header for each request. See the following example for how to set this header in a request or in the SDK.
129129
130130The [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) accepts a personal key or service account key only if the key isn't scoped to a specific workspace.
131131
from line 316
316316 "type": "error",
317317 "error": {
318318 "type": "invalid_request_error",
319 "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
319 "message": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
320320 },
321321 "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
322322}
from line 342
342342
343343If you have a workspace key, you may want to replace it with [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/wif-reference) or a personal or service account key. This provides better security and observability.
344344
345See [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/wif-reference) for details on configuring Workload Identity Federation, which is preferred over long-lived keys.
345See the [WIF reference](https://platform.claude.com/docs/en/manage-claude/wif-reference) for details on configuring Workload Identity Federation, which is preferred over long-lived keys.
346346
347347To replace a workspace key with a personal or service account key:
348348
3493491. **Decide the key type.** Your own tooling should use a personal key. A shared or unattended workload should use a service account key.
3502. **Create a service account** if necessary. You may have to ask an organization admin to create one on the [Service accounts](https://platform.claude.com/settings/service-accounts) page (`platform.claude.com/settings/service-accounts`) in the Claude Console and add it to the relevant workspace.
3502. **Create a service account** if necessary. You might have to ask an organization admin to create one on the [Service accounts](https://platform.claude.com/settings/service-accounts) page (`platform.claude.com/settings/service-accounts`) in the Claude Console and add it to the relevant workspace.
3513513. **Create the new key.** Create it specifically for the integration's workspace unless multiple workspaces are needed.
3524. **Deploy the new key.** Replace the old key wherever the integration reads it, typically the `ANTHROPIC_API_KEY` environment variable or a secrets manager entry. For a multi-workspace key, also send the `anthropic-workspace-id` header as shown in [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace).
3524. **Deploy the new key.** Replace the old key wherever the integration reads it, typically the `ANTHROPIC_API_KEY` environment variable or a secrets manager entry. For a key that isn't scoped to a workspace, also send the `anthropic-workspace-id` header as shown in [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace).
3533535. **Delete the old key.** Confirm that requests succeed, then delete the workspace key on the [API keys page](https://platform.claude.com/settings/keys) in the Claude Console.
354354
355355## Workload Identity Federation
from line 356
356356
357357Workload Identity Federation (WIF) lets a workload authenticate with a short-lived identity token issued by an identity provider (IdP) you already trust, such as AWS IAM, Google Cloud, or any standards-compliant OIDC issuer (such as GitHub Actions, Kubernetes service accounts, SPIFFE, Microsoft Entra ID, or Okta). The workload exchanges its IdP-issued JWT at `POST /v1/oauth/token` for a short-lived Claude API access token, and the SDK refreshes that token automatically before it expires. There is no `sk-ant-api...` string to mint, distribute, or rotate.
358358
359Federation removes long-lived Claude API keys from your environment, which shrinks the blast radius of a leaked credential and lets you manage access with the same IdP controls you already use for cloud resources. It does not, on its own, guarantee end-to-end security: the trust chain is only as strong as your identity provider's configuration, and a long-lived secret one hop upstream (for example, a static cloud credential that can mint IdP tokens) can still undermine it. Pair federation with your provider's controls, such as IP allowlists, MFA, and audit logging.
359Federation removes long-lived Claude API keys from your environment, which limits the damage that a leaked credential can cause and lets you manage access with the same IdP controls you already use for cloud resources. It does not, on its own, guarantee end-to-end security: the trust chain is only as strong as your identity provider's configuration, and a long-lived secret one step earlier in that chain (for example, a static cloud credential that can mint IdP tokens) can still undermine it. Pair federation with your provider's controls, such as IP allowlists, MFA, and audit logging.
360360
361361To configure federation, you create three resources in the Claude Console (a service account, a federation issuer, and a federation rule) and then point your SDK at the rule. See [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) for the full setup walkthrough.
362362
363363## App Attest
364364
365App Attest authenticates iOS and macOS apps that call the Claude API directly from the device. Each installation proves that it is a genuine, unmodified build of an app you registered in the Claude Console, using Apple's App Attest service. Anthropic then issues the device a short-lived access token that bills usage to your workspace. Tokens are scoped to your workspace, expire after one hour, and authorize only [Messages API](https://platform.claude.com/docs/en/api/messages/create) calls.
365App Attest authenticates iOS and macOS apps that call the Claude API directly from the device. Each installation proves that it is a genuine, unmodified build of an app you registered in the Claude Console, using Apple's App Attest service. Anthropic then issues the device a short-lived access token that bills usage to your workspace. Tokens are scoped to your workspace, expire after 1 hour, and authorize only [Messages API](https://platform.claude.com/docs/en/api/messages/create) calls.
366366
367367To register your app and get a client ID, see [App Attest for iOS and macOS apps](https://platform.claude.com/docs/en/manage-claude/app-attest).
368368
manage-claude/claude-code-analytics-api Changed · +6 / -6 lines
from line 8
88 **The Admin API is unavailable for individual accounts.** To collaborate with teammates and add members, set up your organization on the [Organization](https://platform.claude.com/settings/organization) page (`platform.claude.com/settings/organization`) in the Claude Console.
99</Tip>
1010
11The Claude Code Analytics Admin API provides programmatic access to daily aggregated usage metrics for Claude Code users, enabling organizations to analyze developer productivity and build custom dashboards. This API provides more detail than the basic [Analytics dashboard](https://platform.claude.com/claude-code) in the Claude Console, without the complexity of the OpenTelemetry integration.
11The Claude Code Analytics Admin API provides programmatic access to daily aggregated usage metrics for Claude Code users, allowing organizations to analyze developer productivity and build custom dashboards. This API provides more detail than the basic [Analytics dashboard](https://platform.claude.com/claude-code) in the Claude Console, without the complexity of the OpenTelemetry integration.
1212
13This API enables you to better monitor, analyze, and optimize your Claude Code adoption:
13This API allows you to better monitor, analyze, and optimize your Claude Code adoption:
1414
1515* **Developer productivity analysis:** Track sessions, lines of code added/removed, commits, and pull requests created using Claude Code
1616* **Tool usage metrics:** Monitor acceptance and rejection rates for different Claude Code tools (Edit, MultiEdit, Write, NotebookEdit)
from line 63
6363* **Productivity metrics:** Track sessions, lines of code, commits, pull requests, and tool usage
6464* **Token and cost data:** Monitor usage and estimated costs broken down by Claude model
6565* **Cursor-based pagination:** Handle large datasets with stable pagination using opaque cursors
66* **Data freshness:** Metrics are available with up to 1-hour delay for consistency
66* **Data freshness:** Metrics are available with up to a 1-hour delay for consistency
6767
6868For complete parameter details and response schemas, see the [Claude Code Analytics API reference](https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_claude_code).
6969
from line 212
212212
213213The API supports cursor-based pagination for organizations with large numbers of users:
214214
2151. Make your initial request with optional `limit` parameter.
2151. Make your initial request with the optional `limit` parameter.
2162162. If `has_more` is `true` in the response, use the `next_page` value in your next request.
2172173. Continue until `has_more` is `false`.
218218
from line 270
270270
271271### How do I calculate tool acceptance rates?
272272
273Tool acceptance rate = `accepted / (accepted + rejected)` for each tool type. For example, if the edit tool shows 45 accepted and 5 rejected, the acceptance rate is 90%.
273Tool acceptance rate = `accepted / (accepted + rejected)` for each tool type. For example, if the edit tool shows 45 accepted and 5 rejected, the acceptance rate is 90 percent.
274274
275275### What time zone is used for the date parameter?
276276