One read of Claude Developer Platformapi-20260828T173708Z
53 pages moved out of 688 read.
Pages moved
53
significant first
Pages read
688
in this capture
Captured
17:37 UTC
Corpus hash
ca2e3b841543
corpus-hash
What this read moved
1-25 of 53, page 1 of 3This capture is too large to show at once. Changes 1-25 of 53 are below, significant first; the rest are on the following screens.
about-claude/models/optimizing-for-cost-and-intelligence Changed · +32 / -8 lines
#### Defer unused tool definitions #### Keep data files out of the prompt #### Manage the context lifecycle
from line 6
66
77When a workload moves from prototype to production, cost becomes a first-class design constraint. The most capable model can be too expensive at scale, and the least expensive model can fall short on quality. Managing cost well means understanding how each cost lever affects output quality, because some levers trade against quality and some don't. The Claude Platform gives you direct control over that tradeoff. You choose the model, the effort level, and the architecture for each request, which lets you place a workload almost anywhere on the cost-to-intelligence frontier.
88
9Cost and intelligence are usually pictured as a frontier where one buys the other. The first group of levers on this page moves a workload toward that frontier by cutting cost without touching quality; only the second group moves along it:
10
11
12
913The levers come in two kinds:
1014
1115* **Free wins** cut spend without touching quality: prompt caching, token hygiene, a prompt audit against the model you are running, [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) at 50% off for work that can wait up to 24 hours, and [workspace spend limits](https://platform.claude.com/docs/en/api/rate-limits#setting-lower-limits-for-workspaces) as the backstop.
from line 47
4347
4448Turn on [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) before any other lever, because every turn of an agentic task resends the entire growing conversation: system prompt, tool definitions, and every prior turn. A 40-turn task sends its first turn 40 times, so task cost grows with roughly the square of turn count. Caching does not stop the resending, but each resend costs about a tenth as much and processes faster: the prefix is billed at the [cache-read rate](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing), a tenth of the input price, and each turn pays the 1.25x cache-write rate only for what is new.
4549
50**What good looks like.** Over a full day of real traffic, agent loops read a median 84% of their input from the cache, and the top 10% of harnesses, coding or not, read 94% or more[17](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). Deep in a task, a well-built loop pays full price on under 1% of its input. Below about 80%, look for something breaking the cache (see [What breaks the cache](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#what-breaks-the-cache)).
51
4652Across Anthropic's measured runs, cache reads are routinely the largest single component of task cost, making caching worth more than most model-choice decisions. Anthropic priced WideSearch[1](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) and DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) runs with and without caching:
4753
4854
from line 62
5662To decide, count the gaps between consecutive requests in a conversation:
5763
5864* More than about 1 gap in 20 falls between 5 minutes and an hour, and gaps over an hour are rare: use the 1-hour duration.
59* Turns arrive seconds apart: stay on the 5-minute default. With no pauses, it cost 15% less than the 1-hour setting on Claude Sonnet 5 and 11% less on Claude Opus 5.
65* Turns arrive seconds apart: stay on the 5-minute default. When nothing paused, it cost 15% less than the 1-hour setting on Claude Sonnet 5 and 11% less on Claude Opus 5.
6066* Gaps over an hour are common: stay on the default. A gap over an hour expires both durations, and the 1-hour setting then re-writes the prefix at 2x the input price instead of 1.25x, so it loses on each of those gaps. It pays off only when, beyond the 1-in-20 share, gaps between 5 minutes and an hour are at least about two-thirds as frequent as gaps over an hour (each in-band gap saves about 1.15x the prefix; each gap over an hour costs about 0.75x).
6167
62Anthropic measured the 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) with pauses inserted before some turns to simulate a person's delay[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). On both models measured, Claude Sonnet 5 and Claude Opus 5, the 1-hour cache became the cheaper setting once about 3% of turns followed a pause, about 1 turn in 30. The 1-in-20 rule is set above that crossover to leave a margin. With a pause before every turn, the 5-minute setting cost $4.13 per 20-issue session compared with $0.70 for the 1-hour setting on Claude Sonnet 5, and $13.41 compared with $2.70 on Claude Opus 5. Every current model uses the same cache multipliers, so the crossover is in the same range on the other models; the exact share depends on how much of a session the model re-reads. Accuracy stayed within run-to-run noise in every cell. The turn after a pause kept its warm-cache latency on the 1-hour setting. The following chart plots cost per session against the share of paused turns on Claude Sonnet 5:
68Anthropic measured the triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) with pauses inserted before some turns to simulate a person's delay[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). On both models measured, the 1-hour cache became the cheaper setting once about 1 turn in 30 followed a pause, so the 1-in-20 rule leaves a margin, and the gap widens quickly past the crossover because every paused turn on the 5-minute setting re-writes the whole prefix. Every current model uses the same cache multipliers, so the crossover is in the same range on the other models; the exact share depends on how much of a session the model re-reads. Accuracy stayed within run-to-run noise in every cell. The turn after a pause kept its warm-cache latency on the 1-hour setting. The following chart plots cost per session against the share of paused turns on Claude Sonnet 5:
6369
6470
6571
from line 98
9298
9399#### What breaks the cache
94100
95Four things can break your cache during a task. Anything that changes per request, such as a timestamp or a queue position, placed ahead of the stable prefix turns every request into a full cache write: on the triage run in [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), a 25-token status line at the front of the system prompt cost $4.24 per run instead of $0.59, more than running with caching off. Keep per-request text in the newest user turn. Changing [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) between requests invalidates the cached prefix, so change it only where you would re-cache anyway, such as at a [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) boundary. Changing a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) partway through does the same, so set it once, on the first request. Every [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing#context-editing-and-prompt-caching) pass invalidates the prefix from the point it clears and the next request pays to re-cache everything after it, so clear in a few large batches rather than many small ones. Make the last three changes at natural breaks, then confirm cache reads have not dropped; if they have, [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) shows where the prefix diverged.
101Several things can break your cache during a task. Anything that changes per request, such as a timestamp or a queue position, placed ahead of the stable prefix turns every request into a full cache write: on the triage run in [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), a 25-token status line at the front of the system prompt cost $4.24 per run instead of $0.59, more than running with caching off. Keep per-request text in the newest user turn.
96102
103The cache is a byte-exact prefix match over the request in order (tools, then system prompt, then messages), so a change anywhere invalidates everything after it. Changing [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) or the thinking configuration between requests invalidates the cache from that point onward, and on some models the tools and system prompt ahead of it as well; any edit to the system prompt invalidates the cache from that point onward; setting or changing an output format invalidates the cache for the whole conversation; adding, removing, or reordering a tool definition invalidates all of it. The [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache) page lists these cases, apart from the output format, which [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#prompt-modification-and-token-costs) covers. On Claude Opus 5 (and Claude Fable 5, Claude Mythos 5, and Claude Opus 4.8), change instructions with a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), a `{"role": "system"}` message appended to `messages`, instead of editing the top-level `system` field: the cached prefix stays intact. The same page covers mid-conversation tool changes, in beta on those models. Otherwise, make such changes only where you would re-cache anyway, such as at a [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) boundary, and on the first request after the compaction rather than the one that triggers it.
104
105Anthropic measured this on the triage agent's long sessions[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). An effort change and an added tool made mid-session rewrote 39,000 and 60,000 cached tokens, and those sessions cost $0.95 per session. The same two changes on the first request after compaction cost $0.75, and on the request that triggered the compaction $0.92, because the compaction's summarization pass then re-processed the 81,000-token context at the cache-write price: that summarization pass cost $0.21, against $0.04 when the same changes came one request later, with accuracy within run-to-run noise in every arm:
106
107
108
109Changing a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) partway through invalidates any cached prefix that contains the budget value, so set it once, on the first request. Every [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing#context-editing-and-prompt-caching) pass invalidates the prefix from the point it clears and the next request pays to re-cache everything after it, so clear in a few large batches rather than many small ones. Make every cache-invalidating change at natural breaks, then confirm cache reads have not dropped; if they have, [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) shows where the prefix diverged.
110
97111### Trim input and context tokens
98112
99113Most agent requests carry tokens that never influence the answer. Trimming them costs nothing in output quality, although not every lever here saved money when measured. Two places to look:
from line 115
101115* **Input trimming.** [Dynamic filtering](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#dynamic-filtering) in the web fetch tool keeps boilerplate out of fetched pages, [image resizing](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size) right-sizes vision inputs, and [tool search with deferred loading](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) loads tool definitions only when needed (measured later in this section). [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) lets Claude run several tool calls from code so only the filtered result enters the context; its documentation reports 24% fewer input tokens on agentic search benchmarks, with a higher score. [Manage tool context](https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context) compares tool search, programmatic tool calling, prompt caching, and context editing.
102116* **Context lifecycle.** [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) clears stale tool results, and [automatic compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) with its threshold stops long loops from carrying their whole history forward.
103117
104Defer tool definitions you are not using. Every tool definition attached to a request is input on every turn, and a few MCP servers add up to hundreds of them. Anthropic ran the triage agent with its own two tools plus a catalog of real tool definitions from public MCP servers, for a total of up to 502 tools, loading all of them or marking the extras `defer_loading` behind [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool):
118The levers interact with the cache and each other, so judge them by net effect, and use [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) to confirm your cached prefix survives each change. Anthropic measured them on an issue-triage agent working through 20 real bug reports with screenshots from a public repository, and on a longer variant of the same job with 2.6 times the tokens. With caching on, input trimming (image resizing and tool search) took a further 26% off the short run and 21% off the long one.
105119
120#### Defer unused tool definitions
121
122Every tool definition attached to a request is input on every turn, and a few MCP servers add up to hundreds of them. Anthropic ran the triage agent with its own two tools plus a catalog of real tool definitions from public MCP servers, for a total of up to 502 tools, loading all of them or marking the extras `defer_loading` behind [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool):
123
106124
107125
108126With every definition loaded, the run cost rose from $0.55 to $1.02, tracking the schema tokens on each request. With tool search, it stayed at $0.56 at every catalog size, 45% less at 502 tools. Accuracy was 15 to 18 of 20 in every cell either way, and the model never called a wrong tool, so at this scale the catalog costs money, not correctness. The same holds for tools that come through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector): with a public GitHub MCP server attached, deferring its toolset (`default_config: {defer_loading: true}`) cut the run 20% at the same accuracy.
109127
110Keep data files out of the prompt. When the model has to compute over a table, upload it with the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) and let the model query it with [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) instead of pasting it in. Anthropic asked 25 aggregate questions[15](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) (sums, filtered counts, group-bys, and a date filter) over a 1,862-row public CSV, with the answers computed by pandas:
128#### Keep data files out of the prompt
111129
130When the model has to compute over a table, upload it with the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) and let the model query it with [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) instead of pasting it in. Anthropic asked 25 aggregate questions[15](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) (sums, filtered counts, group-bys, and a date filter) over a 1,862-row public CSV, with the answers computed by pandas:
131
112132
113133
114134Pasted into the prompt, the table is about 91,000 input tokens on every request, and Claude Sonnet 5 answered 6 of 25 questions correctly at $5.01 per run. Uploaded, with code execution, it answered 25 of 25 at $0.40. Claude Opus 5 showed the same pattern (6 of 25 at $13.45 against 25 of 25 at $1.91).
115135
116The levers interact with the cache and each other, so judge them by net effect, and use [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) to confirm your cached prefix survives each change. Anthropic measured them on an issue-triage agent working through 20 real bug reports with screenshots from a public repository, and on a longer variant of the same job with 2.6 times the tokens. With caching on, input trimming (image resizing and tool search) took a further 26% off the short run and 21% off the long one. The context levers are where the two runs diverge:
136#### Manage the context lifecycle
117137
138The context levers are where the two runs diverge:
139
118140
119141
120142The context levers only pay on a session long enough to need them. On the 20-issue run, context editing cost 74% more, and compaction and the prune changed nothing. On the long run, context editing changed nothing, compaction saved 32%, and the prune saved 39%. The prune is a few lines you write yourself: at each task boundary, replace large stale tool results with a one-line extract. It caches well because the edits sit at the tail of the conversation, where the next task adds new content anyway: 89% cache reads on the first request after a boundary and 81% on the requests between boundaries. Run-wide, the prune and context editing cache equally well. The prune is cheaper because context editing rewrites content mid-task that the prune deletes (about two thirds of the gap) and because it keeps the context about half the size (the other third). If you use context editing, [clear in a few large batches](https://platform.claude.com/docs/en/build-with-claude/context-editing#context-editing-and-prompt-caching). The prune, adapted from the harness:
from line 688
666688
667689## Benchmarks referenced
668690
669All measurements are Anthropic-internal runs of these benchmarks. Unless noted, costs are USD at the list prices in effect when each benchmark ran; Claude Sonnet 5 figures use $2 and $10 per million input and output tokens. Charts labeled "notional USD" price each request's token counts at those rates rather than reporting invoices.
691Except where a reference says otherwise, measurements are Anthropic-internal runs of these benchmarks. Unless noted, costs are USD at the list prices in effect when each benchmark ran; Claude Sonnet 5 figures use $2 and $10 per million input and output tokens. Charts labeled "notional USD" price each request's token counts at those rates rather than reporting invoices.
670692
6716931. **WideSearch:** Wong et al., "WideSearch: Benchmarking Agentic Broad Info-Seeking," arXiv:2508.07999, 2025. Broad web-research tasks graded on a many-row table's completeness and accuracy; 200 problems, 3 runs per configuration, run August 1 to 2, 2026. The caching chart re-prices the effort chart's default-effort runs from their per-request billing records; per-problem costs differ slightly because the two charts use different cost accounting. The cost-concentration chart is a separate 20-problem run, 3 runs per problem, run August 3 to 4, 2026, costed from per-request billing records.
6726942. **GDPval:** OpenAI, "GDPval: Evaluating AI Model Performance on Real-World Economically Valuable Tasks," 2025. Knowledge-work deliverables graded against task rubrics; a 210-task run of the released gold set, one attempt per task, run August 2, 2026. A Claude model grades, so absolute scores may differ from published results.
from line 703
68170311. **Internal agentic-coding benchmark:** Anthropic-internal: 370 repository tasks graded by the repositories' own tests. The API figures (Opus 5 alone, Fable 5 alone, and the pairing) were measured August 9 to 10, 2026, at the default effort with a 128,000-token output cap, one run per configuration: five attempts per task at the default settings and for the pairing, one at `low` and `medium`; the pairing averaged about two advisor consultations per attempt; costs are per attempt. The Claude Code figures are runs of the same tasks from July 8 to 23, 2026, one run per configuration, costs approximate.
68270412. **Internal repository-task benchmark (cap measurement):** A separate Anthropic-internal set of about 130 repository tasks, run August 8 to 10, 2026, with a plain API agent loop, one attempt per task. The 16,384-token figures average two runs per model; the 64,000-token figures are single runs (124 tasks scored for Opus 5; 108 for Claude Fable 5, the environment having skipped the rest before the model ran). About half the Fable attempts the 16,384 cap had ended solved at 64,000; a further Fable run at 128,000 scored 56.1%, within noise of the 64,000 run. The SWE-bench Pro cap figures are one Claude Fable 5 run per cap (August 10, 2026) at the default effort on a 100-problem subset stratified from reference 3's 482-problem set, not comparable to its scores. The chart's per-turn distributions come from the Opus run at 64,000 and the Fable run at 128,000, so neither is cut off by its own cap.
68370513. **Chartography:** Surge AI, "Chartography," 2026. The complete released 100-question set, measured August 8 to 10, 2026, with Anthropic's implementation on Claude Managed Agents (standard cloud sandbox; advisor configurations use the Managed Agents advisor). Claude Sonnet 4.6 grades instead of the reference judge and the benchmark runs with tools, so scores compare across configurations here but not to the published leaderboard. Two runs per configuration, pooled; run-to-run spreads were 4 to 10 points. Costs exclude sandbox time, which added under 1%. The consult-rate comparison comes from rerunning the same configurations on the Messages API with a container tool set, August 10 to 11, 2026.
68414. **Support-desk prompt-audit evaluation:** An Anthropic-constructed set of 44 support tickets with deterministic grading, run August 2026 under six system prompts, each adding to the same clean prompt one pattern common in prompts written for Claude Opus 4.8 and Claude Sonnet 4.6. Each chart point is one of three cases (older model, newer model on the same prompt, newer model after the audit) averaged over the six prompts and 44 tickets. The Opus 5 accuracy gain has a 95% confidence interval of 3 to 8 points; the Sonnet accuracy differences are within noise.
70614. **Support-desk prompt-audit evaluation:** An Anthropic-constructed set of 44 support tickets with deterministic grading, run in early August 2026 and reported on August 8, 2026, under six system prompts, each adding to the same clean prompt one pattern common in prompts written for Claude Opus 4.8 and Claude Sonnet 4.6. Each chart point is one of three cases (older model, newer model on the same prompt, newer model after the audit) averaged over the six prompts and 44 tickets. The Opus 5 accuracy gain has a 95% confidence interval of 3 to 8 points; the Sonnet accuracy differences are within noise.
68570715. **Data-file question set:** An Anthropic-constructed set of 25 aggregate questions over a 1,862-row slice of a public liquor-sales CSV, with ground truth computed by pandas and exact-match grading, run on Claude Sonnet 5 and Claude Opus 5 with thinking disabled (the in-context arm cannot complete at the default), a 4,000-token output cap, and no prompt caching, three runs per configuration, run August 19, 2026. The file arm uploads the CSV through the Files API and uses the `code_execution_20260120` tool.
68670816. **Cache duration measurement:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run August 23, 2026, on Claude Sonnet 5 and Claude Opus 5 on the Messages API with the same harness, the Claude Opus 5 cells with `max_tokens` raised to 4,096, with pauses inserted before a randomly chosen share of turns (none, 5%, 10%, and every turn at 6 minutes on all 20 issues on both models, plus every turn at 2 minutes on Claude Sonnet 5; 20-minute pauses on a 5-issue subset on both models; 45-minute pauses on a 5-issue subset on Claude Sonnet 5 only). Three runs per cell, cost computed from each response's `usage` fields on a customer-billed organization at list prices, accuracy against the same gold labels. The crossover is about 3.3% of turns on both models: the median of each session's break-even share, computed by the cost model from that session's turn-by-turn context sizes, over all 45 Claude Sonnet 5 and 36 Claude Opus 5 twenty-issue sessions in the analysis (every pause schedule run on the full job, under all three cache settings, three runs each; the 5-issue cells are not in it). The 5% cell tied on Claude Sonnet 5 because that draw's pauses fell on small prefixes. The page's 1-in-20 rule sits above the measured crossover. Anthropic measured keep-alive requests that refresh the 5-minute cache as a comparator only. They matched the 1-hour setting at best and cost more with a pause before every turn, so do not use them.
70917. **Cache-read share in production:** Aggregated first-party Claude API usage for the 14 days ending August 23, 2026, direct API product only, Anthropic-internal organizations excluded, no organization identified. An organization-day counts as an agent loop when its requests carry tool definitions and tool results, its prompts hold 9 or more prior tool calls on average, caching was used, and it made at least 10 such requests (the API has no conversation identifier, so this stands in for conversation length): 303,003 organization-days across 106,487 organizations, median cache-read share 84.2% of all input tokens, upper quartile 91.7%. Use-case labels (the organization's declared use case, or otherwise its classified one) cover 74% of those organization-days and 99% of their tokens; coding organizations supply 87% of agentic input tokens and read a median 88.5% (90.9% at 25 or more prior tool calls), upper quartile 93.4%, with about 72% of coding organization-days at 80% or more; support, research, and data agents read 84% to 85%. The top decile of organization-days reads 95.9% or more for coding and 94.2% to 94.8% for support, research, data, and other agents. The request-level split at 25 or more prior tool calls comes from a six-hour sample: coding 92% read, 7% write, under 1% uncached. Unlabeled organizations, mostly small, read a median 11%. Organization-days with no tool definitions read a median 34.6%. An independent query over the same window that reconstructs conversations of 10 or more requests, rather than scoring organization-days, puts the median at 90.2%; the difference is scope, not data.
71018. **Compaction timing measurement:** The triage agent's long variant from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run August 24, 2026, on Claude Sonnet 5 with the 5-minute cache, cost from the usage fields at list prices, five sessions per arm: a no-change arm at the default effort throughout ($0.81 per session), and two arms that start at low effort and make the same two cache-breaking changes, a switch to the default effort and one added tool, either mid-session at requests 12 and 17 ($0.95) or together on the first request after the first compaction ($0.75). A fourth arm of six sessions, run August 25, 2026, made the same two changes on the request that triggered the first compaction ($0.92 per session): that request's summarization pass wrote the 81,000-token context to the cache instead of reading it, so that pass cost $0.21 against $0.04 for the same pass in the boundary arm. Sessions first compacted at request 21 to 25 (16 of the 21 sessions at request 22), once the prompt passed the 80,000-token compaction trigger, and two no-change sessions compacted a second time near the end. The boundary arm's lower total than the no-change arm reflects its low-effort requests before the change and those second compactions rather than caching: the two arms' re-write costs differ by under a cent. The mid-session arm paid $0.23 per session in cache re-writes; the difference between the mid-session and boundary arms was $0.20 with a 95% confidence interval of $0.11 to $0.29. One mid-session session ran cheap ($0.82) after its model mis-called the search tool following compaction and got empty results; it is included, and without it the arm averages $0.98. Accuracy averaged 14.2 of 20 labels in each August 24 arm and 14.7 in the August 25 arm; cache reads were 91% of prompt tokens with no changes, 85% mid-session, 91% at the boundary, and 86% with the changes on the triggering request.
687711
688712## Next steps
689713
api/admin/external_keys Changed · +9 / -9 lines
from line 911
911911
912912 format: date-time
913913
914### External Key List Response
914### External Key Retrieve Response
915915
916- `ExternalKeyListResponse object`
916- `ExternalKeyRetrieveResponse object`
917917
918918 CMEK external key config belonging to the caller's organization.
919919
from line 1013
10131013
10141014 format: date-time
10151015
1016### External Key Retrieve Response
1016### External Key Update Response
10171017
1018- `ExternalKeyRetrieveResponse object`
1018- `ExternalKeyUpdateResponse object`
10191019
10201020 CMEK external key config belonging to the caller's organization.
10211021
from line 1115
11151115
11161116 format: date-time
11171117
1118### External Key Update Response
1118### External Key List Response
11191119
1120- `ExternalKeyUpdateResponse object`
1120- `ExternalKeyListResponse object`
11211121
11221122 CMEK external key config belonging to the caller's organization.
11231123
api/admin/federation_rules/workspaces Changed · +36 / -36 lines
from line 250
250250
251251## Domain types
252252
253### Workspace List Response
253### Workspace Create Response
254254
255- `WorkspaceListResponse object`
255- `WorkspaceCreateResponse object`
256256
257257 - `created_at: string`
258258
from line 280
280280
281281 Workspace display name. Populated when listing; null in the enable response.
282282
283### Workspace Create Response
283### Workspace List Response
284284
285- `WorkspaceCreateResponse object`
285- `WorkspaceListResponse object`
286286
287287 - `created_at: string`
288288
api/admin/mcp_tunnels Changed · +38 / -38 lines
from line 511
511511 ID of the Workspace this Tunnel belongs to, or `null` for the default
512512 Workspace. Immutable after creation.
513513
514### MCP Tunnel Reveal Token Response
515
516- `MCPTunnelRevealTokenResponse object`
517
518 - `id: string`
519
520 Stable identifier for the current token value. Changes when the token is
521 rotated.
522
523 - `tunnel_token: string`
524
525 The tunnel's connection token.
526
527 - `type: "tunnel_token"`
528
529 Object type. Always `tunnel_token` for Tunnel Tokens.
530
531 default: tunnel_token
532
533### MCP Tunnel Rotate Token Response
534
535- `MCPTunnelRotateTokenResponse object`
536
537 - `id: string`
538
539 Stable identifier for the current token value. Changes when the token is
540 rotated.
541
542 - `tunnel_token: string`
543
544 The tunnel's connection token.
545
546 - `type: "tunnel_token"`
547
548 Object type. Always `tunnel_token` for Tunnel Tokens.
549
550 default: tunnel_token
551
552514### MCP Tunnel Archive Response
553515
554516- `MCPTunnelArchiveResponse object`
from line 552
590552
591553 ID of the Workspace this Tunnel belongs to, or `null` for the default
592554 Workspace. Immutable after creation.
555
556### MCP Tunnel Reveal Token Response
557
558- `MCPTunnelRevealTokenResponse object`
559
560 - `id: string`
561
562 Stable identifier for the current token value. Changes when the token is
563 rotated.
564
565 - `tunnel_token: string`
566
567 The tunnel's connection token.
568
569 - `type: "tunnel_token"`
570
571 Object type. Always `tunnel_token` for Tunnel Tokens.
572
573 default: tunnel_token
574
575### MCP Tunnel Rotate Token Response
576
577- `MCPTunnelRotateTokenResponse object`
578
579 - `id: string`
580
581 Stable identifier for the current token value. Changes when the token is
582 rotated.
583
584 - `tunnel_token: string`
585
586 The tunnel's connection token.
587
588 - `type: "tunnel_token"`
589
590 Object type. Always `tunnel_token` for Tunnel Tokens.
591
592 default: tunnel_token
593593
594594## MCP Tunnels › Tunnel Certificates
595595
api/admin/workspaces/service_accounts Changed · +46 / -46 lines
from line 554
554554
555555 - `"workspace_user"`
556556
557### Service Account List Response
557### Service Account Update Response
558558
559- `ServiceAccountListResponse object`
559- `ServiceAccountUpdateResponse object`
560560
561561 - `created_by_actor_id: string or null`
562562
from line 592
592592
593593 - `"workspace_user"`
594594
595### Service Account Update Response
595### Service Account List Response
596596
597- `ServiceAccountUpdateResponse object`
597- `ServiceAccountListResponse object`
598598
599599 - `created_by_actor_id: string or null`
600600
api/beta Changed · +434 / -376 lines
### Parse Unverified
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 5034
50345034
50355035 format: date-time
50365036
5037 - `skills: array of BetaSkill or null`
5037 - `skills: array of BetaContainerSkill or null`
50385038
50395039 Skills loaded in the container
50405040
from line 8870
88708870
88718871 If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.
88728872
8873 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [we
8873 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g.
api/beta/files Changed · +44 / -28 lines
from line 106
106106
107107 format: binary
108108
109- `expires_in_seconds: optional number`
110
111 Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).
112
113 minimum: 3600, maximum: 7776000
114
109115### Returns
110116
111117- `BetaFileMetadata object`
from line 158
152158
153159 default: false
154160
161 - `expires_at: optional string or null`
162
163 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
164
165 format: date-time
166
155167 - `scope: optional BetaFileScope or null`
156168
157169 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 182
170182curl https://api.anthropic.com/v1/files \
171183 -H 'Content-Type: multipart/form-data' \
172184 -H 'anthropic-version: 2023-06-01' \
173 -H 'anthropic-beta: files-api-2025-04-14' \
174185 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
175186 -F 'file=@/path/to/file'
176187```
from line 197
186197 "size_bytes": 102400,
187198 "type": "file",
188199 "downloadable": false,
200 "expires_at": "2025-05-15T18:37:24.100435Z",
189201 "scope": {
190202 "id": "id",
191203 "type": "session"
from line 213
201213
202214### Query parameters
203215
204- `after_id: optional string`
216- `ids: optional array of string`
205217
206 ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
218 Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.
207219
208- `before_id: optional string`
209
210 ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
211
212220- `limit: optional number`
213221
214222 Number of items to return per page.
from line 225
217225
218226 default: 20, maximum: 1000, minimum: 1
219227
228- `page: optional string`
229
230 Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.
231
220232- `scope_id: optional string`
221233
222234 Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).
from line 373
361373
362374 default: false
363375
376 - `expires_at: optional string or null`
377
378 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
379
380 format: date-time
381
364382 - `scope: optional BetaFileScope or null`
365383
366384 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 391
373391
374392 The type of scope (e.g., `"session"`).
375393
376- `first_id: optional string or null`
394- `next_page: optional string or null`
377395
378 ID of the first file in this page of results.
396 Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results.
379397
380- `has_more: optional boolean`
381
382 Whether there are more results available.
383
384 default: false
385
386- `last_id: optional string or null`
387
388 ID of the last file in this page of results.
389
390398### Example
391399
392400```bash
393401curl https://api.anthropic.com/v1/files \
394402 -H 'anthropic-version: 2023-06-01' \
395 -H 'anthropic-beta: files-api-2025-04-14' \
396403 -H "X-Api-Key: $ANTHROPIC_API_KEY"
397404```
398405
from line 416
409416 "size_bytes": 102400,
410417 "type": "file",
411418 "downloadable": false,
419 "expires_at": "2025-05-15T18:37:24.100435Z",
412420 "scope": {
413421 "id": "id",
414422 "type": "session"
from line 423
415423 }
416424 }
417425 ],
418 "first_id": "file_011CNha8iCJcU1wXNR6q4V8w",
419 "has_more": true,
420 "last_id": "file_013Zva2CMHLNnXjNJJKqJ2EF"
426 "next_page": "next_page"
421427}
422428```
423429
from line 536
530536```bash
531537curl https://api.anthropic.com/v1/files/$FILE_ID/content \
532538 -H 'anthropic-version: 2023-06-01' \
533 -H 'anthropic-beta: files-api-2025-04-14' \
534539 -H "X-Api-Key: $ANTHROPIC_API_KEY"
535540```
536541
from line 689
684689
685690 default: false
686691
692 - `expires_at: optional string or null`
693
694 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
695
696 format: date-time
697
687698 - `scope: optional BetaFileScope or null`
688699
689700 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 712
701712```bash
702713curl https://api.anthropic.com/v1/files/$FILE_ID \
703714 -H 'anthropic-version: 2023-06-01' \
704 -H 'anthropic-beta: files-api-2025-04-14' \
705715 -H "X-Api-Key: $ANTHROPIC_API_KEY"
706716```
707717
from line 726
716726 "size_bytes": 102400,
717727 "type": "file",
718728 "downloadable": false,
729 "expires_at": "2025-05-15T18:37:24.100435Z",
719730 "scope": {
720731 "id": "id",
721732 "type": "session"
from line 860
849860curl https://api.anthropic.com/v1/files/$FILE_ID \
850861 -X DELETE \
851862 -H 'anthropic-version: 2023-06-01' \
852 -H 'anthropic-beta: files-api-2025-04-14' \
853863 -H "X-Api-Key: $ANTHROPIC_API_KEY"
854864```
855865
from line 935
925935 Whether the file can be downloaded.
926936
927937 default: false
938
939 - `expires_at: optional string or null`
940
941 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
942
943 format: date-time
928944
929945 - `scope: optional BetaFileScope or null`
930946
api/beta/files/list Changed · +18 / -24 lines
from line 6
66
77## Query parameters
88
9- `after_id: optional string`
9- `ids: optional array of string`
1010
11 ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
11 Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.
1212
13- `before_id: optional string`
14
15 ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
16
1713- `limit: optional number`
1814
1915 Number of items to return per page.
from line 18
2218
2319 default: 20, maximum: 1000, minimum: 1
2420
21- `page: optional string`
22
23 Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.
24
2525- `scope_id: optional string`
2626
2727 Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).
from line 166
166166
167167 default: false
168168
169 - `expires_at: optional string or null`
170
171 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
172
173 format: date-time
174
169175 - `scope: optional BetaFileScope or null`
170176
171177 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 184
178184
179185 The type of scope (e.g., `"session"`).
180186
181- `first_id: optional string or null`
187- `next_page: optional string or null`
182188
183 ID of the first file in this page of results.
189 Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results.
184190
185- `has_more: optional boolean`
186
187 Whether there are more results available.
188
189 default: false
190
191- `last_id: optional string or null`
192
193 ID of the last file in this page of results.
194
195191## Example
196192
197193```bash
198194curl https://api.anthropic.com/v1/files \
199195 -H 'anthropic-version: 2023-06-01' \
200 -H 'anthropic-beta: files-api-2025-04-14' \
201196 -H "X-Api-Key: $ANTHROPIC_API_KEY"
202197```
203198
from line 209
214209 "size_bytes": 102400,
215210 "type": "file",
216211 "downloadable": false,
212 "expires_at": "2025-05-15T18:37:24.100435Z",
217213 "scope": {
218214 "id": "id",
219215 "type": "session"
from line 216
220216 }
221217 }
222218 ],
223 "first_id": "file_011CNha8iCJcU1wXNR6q4V8w",
224 "has_more": true,
225 "last_id": "file_013Zva2CMHLNnXjNJJKqJ2EF"
219 "next_page": "next_page"
226220}
227221```
228222
api/beta/files/retrieve_metadata Changed · +7 / -1 lines
from line 148
148148
149149 default: false
150150
151 - `expires_at: optional string or null`
152
153 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
154
155 format: date-time
156
151157 - `scope: optional BetaFileScope or null`
152158
153159 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 171
165171```bash
166172curl https://api.anthropic.com/v1/files/$FILE_ID \
167173 -H 'anthropic-version: 2023-06-01' \
168 -H 'anthropic-beta: files-api-2025-04-14' \
169174 -H "X-Api-Key: $ANTHROPIC_API_KEY"
170175```
171176
from line 185
180185 "size_bytes": 102400,
181186 "type": "file",
182187 "downloadable": false,
188 "expires_at": "2025-05-15T18:37:24.100435Z",
183189 "scope": {
184190 "id": "id",
185191 "type": "session"
api/beta/files/upload Changed · +13 / -1 lines
from line 104
104104
105105 format: binary
106106
107- `expires_in_seconds: optional number`
108
109 Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).
110
111 minimum: 3600, maximum: 7776000
112
107113## Returns
108114
109115- `BetaFileMetadata object`
from line 156
150156
151157 default: false
152158
159 - `expires_at: optional string or null`
160
161 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
162
163 format: date-time
164
153165 - `scope: optional BetaFileScope or null`
154166
155167 The scope of this file, indicating the context in which it was created (e.g., a session).
from line 180
168180curl https://api.anthropic.com/v1/files \
169181 -H 'Content-Type: multipart/form-data' \
170182 -H 'anthropic-version: 2023-06-01' \
171 -H 'anthropic-beta: files-api-2025-04-14' \
172183 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
173184 -F 'file=@/path/to/file'
174185```
from line 195
184195 "size_bytes": 102400,
185196 "type": "file",
186197 "downloadable": false,
198 "expires_at": "2025-05-15T18:37:24.100435Z",
187199 "scope": {
188200 "id": "id",
189201 "type": "session"
api/beta/messages Changed · +33 / -33 lines
### Beta Container Skill ### Beta Skill
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 3927
39273927
39283928 format: date-time
39293929
3930 - `skills: array of BetaSkill or null`
3930 - `skills: array of BetaContainerSkill or null`
39313931
39323932 Skills loaded in the container
39333933
from line 8385
83858385
83868386 - `enabled: optional boolean or null`
83878387
8388 Whether this member is offered to the model. Default is per member, per the
8388 Whether this member is offered to the model. Default is per member
api/beta/messages/batches Changed · +4 / -4 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 5154
51545154
51555155 format: date-time
51565156
5157 - `skills: array of BetaSkill or null`
5157 - `skills: array of BetaContainerSkill or null`
51585158
51595159 Skills loaded in the container
51605160
from line 7217
72177217
72187218 format: date-time
72197219
7220 - `skills: array of BetaSkill or null`
7220 - `skills: array of BetaContainerSkill or null`
72217221
72227222 Skills loaded in the container
72237223
from line 8373
83738373
83748374 - `"reasoning_extraction"`
83758375
8376 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).
8377
8378 -
8376 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking
api/beta/organization Changed · +10 / -10 lines
from line 8642
86428642override. Groups without overrides inherit the organization limits and
86438643are not listed; use `GET /v1/organizations/rate_limits` to see those.
86448644
8645This endpoint currently returns every matching entry in a single page
8646regardless of `limit`; follow `next_page` so that clients keep working
8647when pagination is enabled.
8645When `limit` is omitted, every matching entry is returned in a single
8646page; when `limit` truncates the result, follow `next_page` to fetch
8647the remaining entries.
86488648
86498649#### Path parameters
86508650
from line 8674
86748674
86758675 Maximum number of items to return per page. Ranges from `1` to `1000`.
86768676
8677 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
8677 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
86788678
86798679 maximum: 1000, minimum: 1
86808680
from line 8740
87408740
87418741- `next_page: string or null`
87428742
8743 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
8743 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
87448744
87458745#### Example
87468746
from line 10102
1010210102or an API-surface category such as the Files API or Message Batches)
1010310103and contains the set of limiter values that apply to it.
1010410104
10105This endpoint currently returns every matching entry in a single page
10106regardless of `limit`; follow `next_page` so that clients keep working
10107when pagination is enabled.
10105When `limit` is omitted, every matching entry is returned in a single
10106page; when `limit` truncates the result, follow `next_page` to fetch
10107the remaining entries.
1010810108
1010910109#### Query parameters
1011010110
from line 10128
1012810128
1012910129 Maximum number of items to return per page. Ranges from `1` to `1000`.
1013010130
10131 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
10131 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
1013210132
1013310133 maximum: 1000, minimum: 1
1013410134
from line 10190
1019010190
1019110191- `next_page: string or null`
1019210192
10193 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
10193 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
1019410194
1019510195#### Example
1019610196
api/beta/organization/rate_limits Changed · +5 / -5 lines
from line 10
1010or an API-surface category such as the Files API or Message Batches)
1111and contains the set of limiter values that apply to it.
1212
13This endpoint currently returns every matching entry in a single page
14regardless of `limit`; follow `next_page` so that clients keep working
15when pagination is enabled.
13When `limit` is omitted, every matching entry is returned in a single
14page; when `limit` truncates the result, follow `next_page` to fetch
15the remaining entries.
1616
1717### Query parameters
1818
from line 36
3636
3737 Maximum number of items to return per page. Ranges from `1` to `1000`.
3838
39 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
39 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
4040
4141 maximum: 1000, minimum: 1
4242
from line 98
9898
9999- `next_page: string or null`
100100
101 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
101 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
102102
103103### Example
104104
api/beta/organization/rate_limits/list Changed · +5 / -5 lines
from line 8
88or an API-surface category such as the Files API or Message Batches)
99and contains the set of limiter values that apply to it.
1010
11This endpoint currently returns every matching entry in a single page
12regardless of `limit`; follow `next_page` so that clients keep working
13when pagination is enabled.
11When `limit` is omitted, every matching entry is returned in a single
12page; when `limit` truncates the result, follow `next_page` to fetch
13the remaining entries.
1414
1515## Query parameters
1616
from line 34
3434
3535 Maximum number of items to return per page. Ranges from `1` to `1000`.
3636
37 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
37 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
3838
3939 maximum: 1000, minimum: 1
4040
from line 96
9696
9797- `next_page: string or null`
9898
99 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
99 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
100100
101101## Example
102102
api/beta/organization/workspaces Changed · +5 / -5 lines
from line 1095
10951095override. Groups without overrides inherit the organization limits and
10961096are not listed; use `GET /v1/organizations/rate_limits` to see those.
10971097
1098This endpoint currently returns every matching entry in a single page
1099regardless of `limit`; follow `next_page` so that clients keep working
1100when pagination is enabled.
1098When `limit` is omitted, every matching entry is returned in a single
1099page; when `limit` truncates the result, follow `next_page` to fetch
1100the remaining entries.
11011101
11021102#### Path parameters
11031103
from line 1127
11271127
11281128 Maximum number of items to return per page. Ranges from `1` to `1000`.
11291129
1130 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
1130 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
11311131
11321132 maximum: 1000, minimum: 1
11331133
from line 1193
11931193
11941194- `next_page: string or null`
11951195
1196 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
1196 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
11971197
11981198#### Example
11991199
api/beta/organization/workspaces/rate_limits Changed · +5 / -5 lines
from line 10
1010override. Groups without overrides inherit the organization limits and
1111are not listed; use `GET /v1/organizations/rate_limits` to see those.
1212
13This endpoint currently returns every matching entry in a single page
14regardless of `limit`; follow `next_page` so that clients keep working
15when pagination is enabled.
13When `limit` is omitted, every matching entry is returned in a single
14page; when `limit` truncates the result, follow `next_page` to fetch
15the remaining entries.
1616
1717### Path parameters
1818
from line 42
4242
4343 Maximum number of items to return per page. Ranges from `1` to `1000`.
4444
45 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
45 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
4646
4747 maximum: 1000, minimum: 1
4848
from line 108
108108
109109- `next_page: string or null`
110110
111 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
111 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
112112
113113### Example
114114
api/beta/organization/workspaces/rate_limits/list Changed · +5 / -5 lines
from line 8
88override. Groups without overrides inherit the organization limits and
99are not listed; use `GET /v1/organizations/rate_limits` to see those.
1010
11This endpoint currently returns every matching entry in a single page
12regardless of `limit`; follow `next_page` so that clients keep working
13when pagination is enabled.
11When `limit` is omitted, every matching entry is returned in a single
12page; when `limit` truncates the result, follow `next_page` to fetch
13the remaining entries.
1414
1515## Path parameters
1616
from line 40
4040
4141 Maximum number of items to return per page. Ranges from `1` to `1000`.
4242
43 Accepted for request-shape compatibility and currently ignored: every entry is returned in a single page.
43 When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
4444
4545 maximum: 1000, minimum: 1
4646
from line 106
106106
107107- `next_page: string or null`
108108
109 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
109 Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
110110
111111## Example
112112
api/beta/skills Changed · +572 / -581 lines
### Beta Deleted Skill ### Beta Skill ### Beta Skill Source ### Skill Create Response ### Skill List Response ### Skill Retrieve Response ### Skill Delete Response
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 106
106106
107107 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
108108
109- `display_title: optional string or null`
110
111 Display title for the skill.
112
113 This is a human-readable label that is not included in the prompt sent to the model.
109- `display_name: optional string or null`
110
111 Human-readable, single-line label for the Skill. Maximum 255 characters.
112 Always set: derived from the SKILL.md frontmatter `name` when omitted at
113 creation. Not unique.
114114
115115### Returns
116116
117- `id: string`
118
119 Unique identifier for the skill.
120
121 The format and length of IDs may change over time.
122
123- `created_at: string`
124
125 ISO 8601 timestamp of when the skill was created.
126
127- `display_title: string or null`
128
129 Display title for the skill.
130
131 This is a human-readable label that is not included in the prompt sent to the model.
132
133- `latest_version: string or null`
134
135 The latest version identifier for the skill.
136
137 This represents the most recent version of the skill that has been created.
138
139- `source: string`
140
141 Source of the skill.
142
143 This may be one of the following values:
144
145 * `"custom"`: the skill was created by a user
146 * `"anthropic"`: the skill was created by Anthropic
147
148- `type: string`
149
150 Object type.
151
152 For Skills, this is always `"skill"`.
153
154 default: skill
155
156- `updated_at: string`
157
158 ISO 8601 timestamp of when the skill was last updated.
117- `BetaSkill object`
118
119 - `id: string`
120
121 Unique identifier for the skill.
122
123 The format and length of IDs may change over time.
124
125 - `created_at: string`
126
127 ISO 8601 timestamp of when the skill was created.
128
129 format: date-time
130
131 - `display_name: string`
132
133 Human-readable, single-line label for the Skill. Maximum 255 characters.
134 Always set: derived from the SKILL.md frontmatter `name` when omitted at
135 creation. Not unique.
136
137 - `latest_version_id: string`
138
139 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
140
141 - `source: BetaSkillSource`
142
143 Where the Skill comes from.
144
145 Possible values:
146
147 * `"custom"`: authored by the platform user; private to their workspace
148 * `"anthropic"`: published by Anthropic; shared and read-only
149 * `"anthropic_example"`: Anthropic-published sample Skill
150 * `"plugin"`: resolved from an installed plugin
151
152 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
153
154 Where the Skill comes from.
155
156 Possible values:
157
158 * `"custom"`: authored by the platform user; private to their workspace
159 * `"anthropic"`: published by Anthropic; shared and read-only
160 * `"anthropic_example"`: Anthropic-published sample Skill
161 * `"plugin"`: resolved from an installed plugin
162
163 - `"custom"`
164
165 - `"anthropic"`
166
167 - `"anthropic_example"`
168
169 - `"plugin"`
170
171 - `type: "skill"`
172
173 Object type.
174
175 For Skills, this is always `"skill"`.
176
177 default: skill
178
179 - `updated_at: string`
180
181 ISO 8601 timestamp of when the skill was last updated.
182
183 format: date-time
159184
160185### Example
161186
from line 188
163188curl https://api.anthropic.com/v1/skills \
164189 -H 'Content-Type: multipart/form-data' \
165190 -H 'anthropic-version: 2023-06-01' \
166 -H 'anthropic-beta: skills-2025-10-02' \
167191 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
168192 -F files='["Example data"]'
169193```
from line 198
174198{
175199 "id": "skill_01JAbcdefghijklmnopqrstuvw",
176200 "created_at": "2024-10-30T23:58:27.427722Z",
177 "display_title": "My Custom Skill",
178 "latest_version": "1759178010641129",
179 "source": "custom",
180 "type": "type",
201 "display_name": "display_name",
202 "latest_version_id": "latest_version_id",
203 "source": {
204 "type": "custom"
205 },
206 "type": "skill",
181207 "updated_at": "2024-10-30T23:58:27.427722Z"
182208}
183209```
from line 220
194220
195221 Number of results to return per page.
196222
197 Maximum value is 100. Defaults to 20.
198
199 default: 20
223 Ranges from `1` to `1000`. Defaults to `20`.
224
225 default: 20, minimum: 1, maximum: 1000
200226
201227- `page: optional string`
202228
from line 333
307333
308334### Returns
309335
310- `data: array of object`
336- `data: array of BetaSkill`
311337
312338 List of skills.
313339
from line 347
321347
322348 ISO 8601 timestamp of when the skill was created.
323349
324 - `display_title: string or null`
325
326 Display title for the skill.
327
328 This is a human-readable label that is not included in the prompt sent to the model.
329
330 - `latest_version: string or null`
331
332 The latest version identifier for the skill.
333
334 This represents the most recent version of the skill that has been created.
335
336 - `source: string`
337
338 Source of the skill.
339
340 This may be one of the following values:
341
342 * `"custom"`: the skill was created by a user
343 * `"anthropic"`: the skill was created by Anthropic
344
345 - `type: string`
350 format: date-time
351
352 - `display_name: string`
353
354 Human-readable, single-line label for the Skill. Maximum 255 characters.
355 Always set: derived from the SKILL.md frontmatter `name` when omitted at
356 creation. Not unique.
357
358 - `latest_version_id: string`
359
360 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
361
362 - `source: BetaSkillSource`
363
364 Where the Skill comes from.
365
366 Possible values:
367
368 * `"custom"`: authored by the platform user; private to their workspace
369 * `"anthropic"`: published by Anthropic; shared and read-only
370 * `"anthropic_example"`: Anthropic-published sample Skill
371 * `"plugin"`: resolved from an installed plugin
372
373 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
374
375 Where the Skill comes from.
376
377 Possible values:
378
379 * `"custom"`: authored by the platform user; private to their workspace
380 * `"anthropic"`: published by Anthropic; shared and read-only
381 * `"anthropic_example"`: Anthropic-published sample Skill
382 * `"plugin"`: resolved from an installed plugin
383
384 - `"custom"`
385
386 - `"anthropic"`
387
388 - `"anthropic_example"`
389
390 - `"plugin"`
391
392 - `type: "skill"`
346393
347394 Object type.
348395
from line 401
354401
355402 ISO 8601 timestamp of when the skill was last updated.
356403
357- `has_more: boolean`
358
359 Whether there are more results available.
360
361 If `true`, there are additional results that can be fetched using the `next_page` token.
404 format: date-time
362405
363406- `next_page: string or null`
364407
from line 414
371414```bash
372415curl https://api.anthropic.com/v1/skills \
373416 -H 'anthropic-version: 2023-06-01' \
374 -H 'anthropic-beta: skills-2025-10-02' \
375417 -H "X-Api-Key: $ANTHROPIC_API_KEY"
376418```
377419
from line 425
383425 {
384426 "id": "skill_01JAbcdefghijklmnopqrstuvw",
385427 "created_at": "2024-10-30T23:58:27.427722Z",
386 "display_title": "My Custom Skill",
387 "latest_version": "1759178010641129",
388 "source": "custom",
389 "type": "type",
428 "display_name": "display_name",
429 "latest_version_id": "latest_version_id",
430 "source": {
431 "type": "custom"
432 },
433 "type": "skill",
390434 "updated_at": "2024-10-30T23:58:27.427722Z"
391435 }
392436 ],
393 "has_more": true,
394 "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
437 "next_page": "next_page"
395438}
396439```
397440
from line 546
503546
504547### Returns
505548
506- `id: string`
507
508 Unique identifier for the skill.
509
510 The format and length of IDs may change over time.
511
512- `created_at: string`
513
514 ISO 8601 timestamp of when the skill was created.
515
516- `display_title: string or null`
517
518 Display title for the skill.
519
520 This is a human-readable label that is not included in the prompt sent to the model.
521
522- `latest_version: string or null`
523
524 The latest version identifier for the skill.
525
526 This represents the most recent version of the skill that has been created.
527
528- `source: string`
529
530 Source of the skill.
531
532 This may be one of the following values:
533
534 * `"custom"`: the skill was created by a user
535 * `"anthropic"`: the skill was created by Anthropic
536
537- `type: string`
538
539 Object type.
540
541 For Skills, this is always `"skill"`.
542
543 default: skill
544
545- `updated_at: string`
546
547 ISO 8601 timestamp of when the skill was last updated.
549- `BetaSkill object`
550
551 - `id: string`
552
553 Unique identifier for the skill.
554
555 The format and length of IDs may change over time.
556
557 - `created_at: string`
558
559 ISO 8601 timestamp of when the skill was created.
560
561 format: date-time
562
563 - `display_name: string`
564
565 Human-readable, single-line label for the Skill. Maximum 255 characters.
566 Always set: derived from the SKILL.md frontmatter `name` when omitted at
567 creation. Not unique.
568
569 - `latest_version_id: string`
570
571 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
572
573 - `source: BetaSkillSource`
574
575 Where the Skill comes from.
576
577 Possible values:
578
579 * `"custom"`: authored by the platform user; private to their workspace
580 * `"anthropic"`: published by Anthropic; shared and read-only
581 * `"anthropic_example"`: Anthropic-published sample Skill
582 * `"plugin"`: resolved from an installed plugin
583
584 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
585
586 Where the Skill comes from.
587
588 Possible values:
589
590 * `"custom"`: authored by the platform user; private to their workspace
591 * `"anthropic"`: published by Anthropic; shared and read-only
592 * `"anthropic_example"`: Anthropic-published sample Skill
593 * `"plugin"`: resolved from an installed plugin
594
595 - `"custom"`
596
597 - `"anthropic"`
598
599 - `"anthropic_example"`
600
601 - `"plugin"`
602
603 - `type: "skill"`
604
605 Object type.
606
607 For Skills, this is always `"skill"`.
608
609 default: skill
610
611 - `updated_at: string`
612
613 ISO 8601 timestamp of when the skill was last updated.
614
615 format: date-time
548616
549617### Example
550618
551619```bash
552620curl https://api.anthropic.com/v1/skills/$SKILL_ID \
553621 -H 'anthropic-version: 2023-06-01' \
554 -H 'anthropic-beta: skills-2025-10-02' \
555622 -H "X-Api-Key: $ANTHROPIC_API_KEY"
556623```
557624
from line 628
561628{
562629 "id": "skill_01JAbcdefghijklmnopqrstuvw",
563630 "created_at": "2024-10-30T23:58:27.427722Z",
564 "display_title": "My Custom Skill",
565 "latest_version": "1759178010641129",
566 "source": "custom",
567 "type": "type",
631 "display_name": "display_name",
632 "latest_version_id": "latest_version_id",
633 "source": {
634 "type": "custom"
635 },
636 "type": "skill",
568637 "updated_at": "2024-10-30T23:58:27.427722Z"
569638}
570639```
from line 746
677746
678747### Returns
679748
680- `id: string`
681
682 Unique identifier for the skill.
683
684 The format and length of IDs may change over time.
685
686- `type: string`
687
688 Deleted object type.
689
690 For Skills, this is always `"skill_deleted"`.
691
692 default: skill_deleted
749- `BetaDeletedSkill object`
750
751 - `id: string`
752
753 Unique identifier for the skill.
754
755 The format and length of IDs may change over time.
756
757 - `type: "skill_deleted"`
758
759 Deleted object type.
760
761 For Skills, this is always `"skill_deleted"`.
762
763 default: skill_deleted
693764
694765### Example
695766
from line 768
697768curl https://api.anthropic.com/v1/skills/$SKILL_ID \
698769 -X DELETE \
699770 -H 'anthropic-version: 2023-06-01' \
700 -H 'anthropic-beta: skills-2025-10-02' \
701771 -H "X-Api-Key: $ANTHROPIC_API_KEY"
702772```
703773
from line 776
706776```json
707777{
708778 "id": "skill_01JAbcdefghijklmnopqrstuvw",
709 "type": "type"
779 "type": "skill_deleted"
710780}
711781```
712782
713783## Domain types
714784
715### Skill Create Response
716
717- `SkillCreateResponse object`
785### Beta Deleted Skill
786
787- `BetaDeletedSkill object`
718788
719789 - `id: string`
720790
from line 792
722792
723793 The format and length of IDs may change over time.
724794
795 - `type: "skill_deleted"`
796
797 Deleted object type.
798
799 For Skills, this is always `"skill_deleted"`.
800
801 default: skill_deleted
802
803### Beta Skill
804
805- `BetaSkill object`
806
807 - `id: string`
808
809 Unique identifier for the skill.
810
811 The format and length of IDs may change over time.
812
725813 - `created_at: string`
726814
727815 ISO 8601 timestamp of when the skill was created.
728816
729 - `display_title: string or null`
730
731 Display title for the skill.
732
733 This is a human-readable label that is not included in the prompt sent to the model.
734
735 - `latest_version: string or null`
736
737 The latest version identifier for the skill.
738
739 This represents the most recent version of the skill that has been created.
740
741 - `source: string`
742
743 Source of the skill.
744
745 This may be one of the following values:
746
747 * `"custom"`: the skill was created by a user
748 * `"anthropic"`: the skill was created by Anthropic
749
750 - `type: string`
817 format: date-time
818
819 - `display_name: string`
820
821 Human-readable, single-line label for the Skill. Maximum 255 characters.
822 Always set: derived from the SKILL.md frontmatter `name` when omitted at
823 creation. Not unique.
824
825 - `latest_version_id: string`
826
827 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
828
829 - `source: BetaSkillSource`
830
831 Where the Skill comes from.
832
833 Possible values:
834
835 * `"custom"`: authored by the platform user; private to their workspace
836 * `"anthropic"`: published by Anthropic; shared and read-only
837 * `"anthropic_example"`: Anthropic-published sample Skill
838 * `"plugin"`: resolved from an installed plugin
839
840 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
841
842 Where the Skill comes from.
843
844 Possible values:
845
846 * `"custom"`: authored by the platform user; private to their workspace
847 * `"anthropic"`: published by Anthropic; shared and read-only
848 * `"anthropic_example"`: Anthropic-published sample Skill
849 * `"plugin"`: resolved from an installed plugin
850
851 - `"custom"`
852
853 - `"anthropic"`
854
855 - `"anthropic_example"`
856
857 - `"plugin"`
858
859 - `type: "skill"`
751860
752861 Object type.
753862
from line 868
759868
760869 ISO 8601 timestamp of when the skill was last updated.
761870
762### Skill List Response
763
764- `SkillListResponse object`
871 format: date-time
872
873### Beta Skill Source
874
875- `BetaSkillSource object`
876
877 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
878
879 Where the Skill comes from.
880
881 Possible values:
882
883 * `"custom"`: authored by the platform user; private to their workspace
884 * `"anthropic"`: published by Anthropic; shared and read-only
885 * `"anthropic_example"`: Anthropic-published sample Skill
886 * `"plugin"`: resolved from an installed plugin
887
888 - `"custom"`
889
890 - `"anthropic"`
891
892 - `"anthropic_example"`
893
894 - `"plugin"`
895
896## Skills › Versions
897
898### Create Skill Version
899
900**POST** `/v1/skills/{skill_id}/versions`
901
902Create Skill Version
903
904#### Path parameters
905
906- `skill_id: string`
907
908 Unique identifier for the skill.
909
910 The format and length of IDs may change over time.
911
912#### Headers
913
914- `"anthropic-beta": optional array of AnthropicBeta`
915
916 Optional header to specify the beta version(s) you want to use.
917
918 - `string`
919
920 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 38 more`
921
922 - `"message-batches-2024-09-24"`
923
924 - `"prompt-caching-2024-07-31"`
925
926 - `"computer-use-2024-10-22"`
927
928 - `"computer-use-2025-01-24"`
929
930 - `"pdfs-2024-09-25"`
931
932 - `"token-counting-2024-11-01"`
933
934 - `"token-efficient-tools-2025-02-19"`
935
936 - `"output-128k-2025-02-19"`
937
938 - `"files-api-2025-04-14"`
939
940 - `"mcp-client-2025-04-04"`
941
942 - `"mcp-client-2025-11-20"`
943
944 - `"dev-full-thinking-2025-05-14"`
945
946 - `"interleaved-thinking-2025-05-14"`
947
948 - `"code-execution-2025-05-22"`
949
950 - `"extended-cache-ttl-2025-04-11"`
951
952 - `"context-1m-2025-08-07"`
953
954 - `"context-management-2025-06-27"`
955
956 - `"model-context-window-exceeded-2025-08-26"`
957
958 - `"skills-2025-10-02"`
959
960 - `"fast-mode-2026-02-01"`
961
962 - `"output-300k-2026-03-24"`
963
964 - `"user-profiles-2026-03-24"`
965
966 - `"user-profiles-2026-08-18"`
967
968 - `"advisor-tool-2026-03-01"`
969
970 - `"managed-agents-2026-04-01"`
971
972 - `"cache-diagnosis-2026-04-07"`
973
974 - `"dreaming-2026-04-21"`
975
976 - `"thinking-token-count-2026-05-13"`
977
978 - `"server-side-fallback-2026-06-01"`
979
980 - `"server-side-fallback-2026-07-01"`
981
982 - `"fallback-credit-2026-06-01"`
983
984 - `"fallback-credit-2026-07-01"`
985
986 - `"agent-memory-2026-07-22"`
987
988 - `"mid-conversation-tool-changes-2026-07-01"`
989
990 - `"compact-2026-01-12"`
991
992 - `"computer-use-2025-11-24"`
993
994 - `"mcp-tunnels-2026-06-22"`
995
996 - `"structured-outputs-2025-11-13"`
997
998 - `"task-budgets-2026-03-13"`
999
1000 - `"thinking-display-updates-2026-08-18"`
1001
1002 - `"ce-user-management-2026-07-13"`
1003
1004#### Body parameters (form-data)
1005
1006- `files: array of string`
1007
1008 Files to upload for the skill.
1009
1010 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
1011
1012#### Returns
1013
1014- `BetaSkillVersion object`
7651015
7661016 - `id: string`
7671017
1018 Unique identifier for this Skill Version. The id addresses the version in
1019 paths and pins it in references.
1020
1021 - `created_at: string`
1022
1023 ISO 8601 timestamp of when the skill was created.
1024
1025 format: date-time
1026
1027 - `description: string`
1028
1029 Description of the skill version.
1030
1031 This is extracted from the SKILL.md file in the skill upload.
1032
1033 - `name: string`
1034
1035 The Skill's immutable kebab-case slug, set at creation from the first
1036 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
1037 later upload must resolve to the same value. Also the top-level directory
1038 of the Skill's mounted files and the base name of a downloaded archive.
1039
1040 - `skill_id: string`
1041
7681042 Unique identifier for the skill.
7691043
7701044 The format and length of IDs may change over time.
7711045
772 - `created_at: string`
773
774 ISO 8601 timestamp of when the skill was created.
775
776 - `display_title: string or null`
777
778 Display title for the skill.
779
780 This is a human-readable label that is not included in the prompt sent to the model.
781
782 - `latest_version: string or null`
783
784 The latest version identifier for the skill.
785
786 This represents the most recent version of the skill that has been created.
787
788 - `source: string`
789
790 Source of the skill.
791
792 This may be one of the following values:
793
794 * `"custom"`: the skill was created by a user
795 * `"anthropic"`: the skill was created by Anthropic
796
797 - `type: string`
1046 - `type: "skill_version"`
7981047
7991048 Object type.
8001049
801 For Skills, this is always `"skill"`.
802
803 default: skill
804
805 - `updated_at: string`
806
807 ISO 8601 timestamp of when the skill was last updated.
808
809### Skill Retrieve Response
810
811- `SkillRetrieveResponse object`
812
813 - `id: string`
814
815 Unique identifier for the skill.
816
817 The format and length of IDs may change over time.
818
819 - `created_at: string`
820
821 ISO 8601 timestamp of when the skill was created.
822
823 - `display_title: string or null`
824
825 Display title for the skill.
826
827 This is a human-readable label that is not included in the prompt sent to the model.
828
829 - `latest_version: string or null`
830
831 The latest version identifier for the skill.
832
833 This represents the most recent version of the skill that has been created.
834
835 - `source: string`
836
837 Source of the skill.
838
839 This may be one of the following values:
840
841 * `"custom"`: the skill was created by a user
842 * `"anthropic"`: the skill was created by Anthropic
843
844 - `type: string`
845
846 Object type.
847
848 For Skills, this is always `"skill"`.
849
850 default: skill
851
852 - `updated_at: string`
853
854 ISO 8601 timestamp of when the skill was last updated.
855
856### Skill Delete Response
857
858- `SkillDeleteResponse object`
859
860 - `id: string`
861
862 Unique identifier for the skill.
863
864 The format and length of IDs may change over time.
865
866 - `type: string`
867
868 Deleted object type.
869
870 For Skills, this is always `"skill_deleted"`.
871
872 default: skill_deleted
873
874## Skills › Versions
875
876### Create Skill Version
877
878**POST** `/v1/skills/{skill_id}/versions`
879
880Create Skill Version
881
882#### Path parameters
883
884- `skill_id: string`
885
886 Unique identifier for the skill.
887
888 The format and length of IDs may change over time.
889
890#### Headers
891
892- `"anthropic-beta": optional array of AnthropicBeta`
893
894 Optional header to specify the beta version(s) you want to use.
895
896 - `string`
897
898 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 38 more`
899
900 - `"message-batches-2024-09-24"`
901
902 - `"prompt-caching-2024-07-31"`
903
904 - `"computer-use-2024-10-22"`
905
906 - `"computer-use-2025-01-24"`
907
908 - `"pdfs-2024-09-25"`
909
910 - `"token-counting-2024-11-01"`
911
912 - `"token-efficient-tools-2025-02-19"`
913
914 - `"output-128k-2025-02-19"`
915
916 - `"files-api-2025-04-14"`
917
918 - `"mcp-client-2025-04-04"`
919
920 - `"mcp-client-2025-11-20"`
921
922 - `"dev-full-thinking-2025-05-14"`
923
924 - `"interleaved-thinking-2025-05-14"`
925
926 - `"code-execution-2025-05-22"`
927
928 - `"extended-cache-ttl-2025-04-11"`
929
930 - `"context-1m-2025-08-07"`
931
932 - `"context-management-2025-06-27"`
933
934 - `"model-context-window-exceeded-2025-08-26"`
935
936 - `"skills-2025-10-02"`
937
938 - `"fast-mode-2026-02-01"`
939
940 - `"output-300k-2026-03-24"`
941
942 - `"user-profiles-2026-03-24"`
943
944 - `"user-profiles-2026-08-18"`
945
946 - `"advisor-tool-2026-03-01"`
947
948 - `"managed-agents-2026-04-01"`
949
950 - `"cache-diagnosis-2026-04-07"`
951
952 - `"dreaming-2026-04-21"`
953
954 - `"thinking-token-count-2026-05-13"`
955
956 - `"server-side-fallback-2026-06-01"`
957
958 - `"server-side-fallback-2026-07-01"`
959
960 - `"fallback-credit-2026-06-01"`
961
962 - `"fallback-credit-2026-07-01"`
963
964 - `"agent-memory-2026-07-22"`
965
966 - `"mid-conversation-tool-changes-2026-07-01"`
967
968 - `"compact-2026-01-12"`
969
970 - `"computer-use-2025-11-24"`
971
972 - `"mcp-tunnels-2026-06-22"`
973
974 - `"structured-outputs-2025-11-13"`
975
976 - `"task-budgets-2026-03-13"`
977
978 - `"thinking-display-updates-2026-08-18"`
979
980 - `"ce-user-management-2026-07-13"`
981
982#### Body parameters (form-data)
983
984- `files: array of string`
985
986 Files to upload for the skill.
987
988 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
989
990#### Returns
991
992- `id: string`
993
994 Unique identifier for the skill version.
995
996 The format and length of IDs may change over time.
997
998- `created_at: string`
999
1000 ISO 8601 timestamp of when the skill version was created.
1001
1002- `description: string`
1003
1004 Description of the skill version.
1005
1006 This is extracted from the SKILL.md file in the skill upload.
1007
1008- `directory: string`
1009
1010 Directory name of the skill version.
1011
1012 This is the top-level directory name that was extracted from the uploaded files.
1013
1014- `name: string`
1015
1016 Human-readable name of the skill version.
1017
1018 This is extracted from the SKILL.md file in the skill upload.
1019
1020- `skill_id: string`
1021
1022 Identifier for the skill that this version belongs to.
1023
1024- `type: string`
1025
1026 Object type.
1027
1028 For Skill Versions, this is always `"skill_version"`.
1029
1030 default: skill_version
1031
1032- `version: string`
1033
1034 Version identifier for the skill.
1035
1036 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1050 For Skill Versions, this is always `"skill_version"`.
1051
1052 default: skill_version
10371053
10381054#### Example
10391055
from line 1057
10411057curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
10421058 -H 'Content-Type: multipart/form-data' \
10431059 -H 'anthropic-version: 2023-06-01' \
1044 -H 'anthropic-beta: skills-2025-10-02' \
10451060 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
10461061 -F files='["Example data"]'
10471062```
from line 1065
10501065
10511066```json
10521067{
1053 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
1068 "id": "id",
10541069 "created_at": "2024-10-30T23:58:27.427722Z",
1055 "description": "A custom skill for doing something useful",
1056 "directory": "my-skill",
1057 "name": "my-skill",
1070 "description": "description",
1071 "name": "name",
10581072 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
1059 "type": "type",
1060 "version": "1759178010641129"
1073 "type": "skill_version"
10611074}
10621075```
10631076
from line 1092
10791092
10801093- `limit: optional number`
10811094
1082 Number of items to return per page.
1083
1084 Defaults to `20`. Ranges from `1` to `1000`.
1095 Number of results to return per page.
1096
1097 Ranges from `1` to `1000`. Defaults to `20`.
1098
1099 default: 20, minimum: 1, maximum: 1000
10851100
10861101- `page: optional string`
10871102
from line 1196
11811196
11821197#### Returns
11831198
1184- `data: array of object`
1185
1186 List of skill versions.
1199- `data: array of BetaSkillVersion`
1200
1201 List of skills.
11871202
11881203 - `id: string`
11891204
1190 Unique identifier for the skill version.
1205 Unique identifier for this Skill Version. The id addresses the version in
1206 paths and pins it in references.
1207
1208 - `created_at: string`
1209
1210 ISO 8601 timestamp of when the skill was created.
1211
1212 format: date-time
1213
1214 - `description: string`
1215
1216 Description of the skill version.
1217
1218 This is extracted from the SKILL.md file in the skill upload.
1219
1220 - `name: string`
1221
1222 The Skill's immutable kebab-case slug, set at creation from the first
1223 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
1224 later upload must resolve to the same value. Also the top-level directory
1225 of the Skill's mounted files and the base name of a downloaded archive.
1226
1227 - `skill_id: string`
1228
1229 Unique identifier for the skill.
11911230
11921231 The format and length of IDs may change over time.
11931232
1194 - `created_at: string`
1195
1196 ISO 8601 timestamp of when the skill version was created.
1197
1198 - `description: string`
1199
1200 Description of the skill version.
1201
1202 This is extracted from the SKILL.md file in the skill upload.
1203
1204 - `directory: string`
1205
1206 Directory name of the skill version.
1207
1208 This is the top-level directory name that was extracted from the uploaded files.
1209
1210 - `name: string`
1211
1212 Human-readable name of the skill version.
1213
1214 This is extracted from the SKILL.md file in the skill upload.
1215
1216 - `skill_id: string`
1217
1218 Identifier for the skill that this version belongs to.
1219
1220 - `type: string`
1233 - `type: "skill_version"`
12211234
12221235 Object type.
12231236
from line 1238
12251238
12261239 default: skill_version
12271240
1228 - `version: string`
1229
1230 Version identifier for the skill.
1231
1232 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1233
1234- `has_more: boolean`
1235
1236 Indicates if there are more results in the requested page direction.
1237
12381241- `next_page: string or null`
12391242
1240 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
1243 Token for fetching the next page of results.
1244
1245 If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page.
12411246
12421247#### Example
12431248
12441249```bash
12451250curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
12461251 -H 'anthropic-version: 2023-06-01' \
1247 -H 'anthropic-beta: skills-2025-10-02' \
12481252 -H "X-Api-Key: $ANTHROPIC_API_KEY"
12491253```
12501254
from line 1258
12541258{
12551259 "data": [
12561260 {
1257 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
1261 "id": "id",
12581262 "created_at": "2024-10-30T23:58:27.427722Z",
1259 "description": "A custom skill for doing something useful",
1260 "directory": "my-skill",
1261 "name": "my-skill",
1263 "description": "description",
1264 "name": "name",
12621265 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
1263 "type": "type",
1264 "version": "1759178010641129"
1266 "type": "skill_version"
12651267 }
12661268 ],
1267 "has_more": true,
1268 "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
1269 "next_page": "next_page"
12691270}
12701271```
12711272
from line 1286
12851286
12861287- `version: string`
12871288
1288 Version identifier for the skill.
1289
1290 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1289 Identifies the skill version by its version ID.
1290
1291 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
12911292
12921293#### Headers
12931294
from line 1387
13861387```bash
13871388curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
13881389 -H 'anthropic-version: 2023-06-01' \
1389 -H 'anthropic-beta: skills-2025-10-02' \
13901390 -H "X-Api-Key: $ANTHROPIC_API_KEY"
13911391```
13921392
from line 1406
14061406
14071407- `version: string`
14081408
1409 Version identifier for the skill.
1410
1411 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1409 Identifies the skill version: a version ID, or the literal `latest` for the skill's most recent version.
1410
1411 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
14121412
14131413#### Headers
14141414
from line 1504
15041504
15051505#### Returns
15061506
1507- `id: string`
1508
1509 Unique identifier for the skill version.
1510
1511 The format and length of IDs may change over time.
1512
1513- `created_at: string`
1514
1515 ISO 8601 timestamp of when the skill version was created.
1516
1517- `description: string`
1518
1519 Description of the skill version.
1520
1521 This is extracted from the SKILL.md file in the skill upload.
1522
1523- `directory: string`
1524
1525 Directory name of the skill version.
1526
1527 This is the top-level directory name that was extracted from the uploaded files.
1528
1529- `name: string`
1530
1531 Human-readable name of the skill version.
1532
1533 This is extracted from the SKILL.md file in the skill upload.
1534
1535- `skill_id: string`
1536
1537 Identifier for the skill that this version belongs to.
1538
1539- `type: string`
1540
1541 Object type.
1542
1543 For Skill Versions, this is always `"skill_version"`.
1544
1545 default: skill_version
1546
1547- `version: string`
1548
1549 Version identifier for the skill.
1550
1551 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1507- `BetaSkillVersion object`
1508
1509 - `id: string`
1510
1511 Unique identifier for this Skill Version. The id addresses the version in
1512 paths and pins it in references.
1513
1514 - `created_at: string`
1515
1516 ISO 8601 timestamp of when the skill was created.
1517
1518 format: date-time
1519
1520 - `description: string`
1521
1522 Description of the skill version.
1523
1524 This is extracted from the SKILL.md file in the skill upload.
1525
1526 - `name: string`
1527
1528 The Skill's immutable kebab-case slug, set at creation from the first
1529 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
1530 later upload must resolve to the same value. Also the top-level directory
1531 of the Skill's mounted files and the base name of a downloaded archive.
1532
1533 - `skill_id: string`
1534
1535 Unique identifier for the skill.
1536
1537 The format and length of IDs may change over time.
1538
1539 - `type: "skill_version"`
1540
1541 Object type.
1542
1543 For Skill Versions, this is always `"skill_version"`.
1544
1545 default: skill_version
15521546
15531547#### Example
15541548
15551549```bash
15561550curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
15571551 -H 'anthropic-version: 2023-06-01' \
1558 -H 'anthropic-beta: skills-2025-10-02' \
15591552 -H "X-Api-Key: $ANTHROPIC_API_KEY"
15601553```
15611554
from line 1556
15631556
15641557```json
15651558{
1566 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
1559 "id": "id",
15671560 "created_at": "2024-10-30T23:58:27.427722Z",
1568 "description": "A custom skill for doing something useful",
1569 "directory": "my-skill",
1570 "name": "my-skill",
1561 "description": "description",
1562 "name": "name",
15711563 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
1572 "type": "type",
1573 "version": "1759178010641129"
1564 "type": "skill_version"
15741565}
15751566```
15761567
from line 1581
15901581
15911582- `version: string`
15921583
1593 Version identifier for the skill.
1594
1595 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1584 Identifies the skill version by its version ID.
1585
1586 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
15961587
15971588#### Headers
15981589
from line 1679
16881679
16891680#### Returns
16901681
1691- `id: string`
1692
1693 Version identifier for the skill.
1694
1695 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1696
1697- `type: string`
1698
1699 Deleted object type.
1700
1701 For Skill Versions, this is always `"skill_version_deleted"`.
1702
1703 default: skill_version_deleted
1682- `BetaDeletedSkillVersion object`
1683
1684 - `id: string`
1685
1686 Unique identifier for this Skill Version. The id addresses the version in
1687 paths and pins it in references.
1688
1689 - `type: "skill_version_deleted"`
1690
1691 Deleted object type.
1692
1693 For Skill Versions, this is always `"skill_version_deleted"`.
1694
1695 default: skill_version_deleted
17041696
17051697#### Example
17061698
from line 1700
17081700curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
17091701 -X DELETE \
17101702 -H 'anthropic-version: 2023-06-01' \
1711 -H 'anthropic-beta: skills-2025-10-02' \
17121703 -H "X-Api-Key: $ANTHROPIC_API_KEY"
17131704```
17141705
from line 1707
17161707
17171708```json
17181709{
1719 "id": "1759178010641129",
1720 "type": "type"
1710 "id": "id",
1711 "type": "skill_version_deleted"
17211712}
17221713```
17231714
api/beta/skills/create Changed · +78 / -52 lines
from line 104
104104
105105 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
106106
107- `display_title: optional string or null`
107- `display_name: optional string or null`
108108
109 Display title for the skill.
109 Human-readable, single-line label for the Skill. Maximum 255 characters.
110 Always set: derived from the SKILL.md frontmatter `name` when omitted at
111 creation. Not unique.
110112
111 This is a human-readable label that is not included in the prompt sent to the model.
112
113113## Returns
114114
115- `id: string`
115- `BetaSkill object`
116116
117 Unique identifier for the skill.
117 - `id: string`
118118
119 The format and length of IDs may change over time.
119 Unique identifier for the skill.
120120
121- `created_at: string`
121 The format and length of IDs may change over time.
122122
123 ISO 8601 timestamp of when the skill was created.
123 - `created_at: string`
124124
125- `display_title: string or null`
125 ISO 8601 timestamp of when the skill was created.
126126
127 Display title for the skill.
127 format: date-time
128128
129 This is a human-readable label that is not included in the prompt sent to the model.
129 - `display_name: string`
130130
131- `latest_version: string or null`
131 Human-readable, single-line label for the Skill. Maximum 255 characters.
132 Always set: derived from the SKILL.md frontmatter `name` when omitted at
133 creation. Not unique.
132134
133 The latest version identifier for the skill.
135 - `latest_version_id: string`
134136
135 This represents the most recent version of the skill that has been created.
137 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
136138
137- `source: string`
139 - `source: BetaSkillSource`
138140
139 Source of the skill.
141 Where the Skill comes from.
140142
141 This may be one of the following values:
143 Possible values:
142144
143 * `"custom"`: the skill was created by a user
144 * `"anthropic"`: the skill was created by Anthropic
145 * `"custom"`: authored by the platform user; private to their workspace
146 * `"anthropic"`: published by Anthropic; shared and read-only
147 * `"anthropic_example"`: Anthropic-published sample Skill
148 * `"plugin"`: resolved from an installed plugin
145149
146- `type: string`
150 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
147151
148 Object type.
152 Where the Skill comes from.
149153
150 For Skills, this is always `"skill"`.
154 Possible values:
151155
152 default: skill
156 * `"custom"`: authored by the platform user; private to their workspace
157 * `"anthropic"`: published by Anthropic; shared and read-only
158 * `"anthropic_example"`: Anthropic-published sample Skill
159 * `"plugin"`: resolved from an installed plugin
153160
154- `updated_at: string`
161 - `"custom"`
155162
156 ISO 8601 timestamp of when the skill was last updated.
163 - `"anthropic"`
157164
165 - `"anthropic_example"`
166
167 - `"plugin"`
168
169 - `type: "skill"`
170
171 Object type.
172
173 For Skills, this is always `"skill"`.
174
175 default: skill
176
177 - `updated_at: string`
178
179 ISO 8601 timestamp of when the skill was last updated.
180
181 format: date-time
182
158183## Example
159184
160185```bash
from line 186
161186curl https://api.anthropic.com/v1/skills \
162187 -H 'Content-Type: multipart/form-data' \
163188 -H 'anthropic-version: 2023-06-01' \
164 -H 'anthropic-beta: skills-2025-10-02' \
165189 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
166190 -F files='["Example data"]'
167191```
from line 196
172196{
173197 "id": "skill_01JAbcdefghijklmnopqrstuvw",
174198 "created_at": "2024-10-30T23:58:27.427722Z",
175 "display_title": "My Custom Skill",
176 "latest_version": "1759178010641129",
177 "source": "custom",
178 "type": "type",
199 "display_name": "display_name",
200 "latest_version_id": "latest_version_id",
201 "source": {
202 "type": "custom"
203 },
204 "type": "skill",
179205 "updated_at": "2024-10-30T23:58:27.427722Z"
180206}
181207```
api/beta/skills/delete Changed · +10 / -9 lines
from line 106
106106
107107## Returns
108108
109- `id: string`
109- `BetaDeletedSkill object`
110110
111 Unique identifier for the skill.
111 - `id: string`
112112
113 The format and length of IDs may change over time.
113 Unique identifier for the skill.
114114
115- `type: string`
115 The format and length of IDs may change over time.
116116
117 Deleted object type.
117 - `type: "skill_deleted"`
118118
119 For Skills, this is always `"skill_deleted"`.
119 Deleted object type.
120120
121 default: skill_deleted
121 For Skills, this is always `"skill_deleted"`.
122122
123 default: skill_deleted
124
123125## Example
124126
125127```bash
from line 128
126128curl https://api.anthropic.com/v1/skills/$SKILL_ID \
127129 -X DELETE \
128130 -H 'anthropic-version: 2023-06-01' \
129 -H 'anthropic-beta: skills-2025-10-02' \
130131 -H "X-Api-Key: $ANTHROPIC_API_KEY"
131132```
132133
from line 136
135136```json
136137{
137138 "id": "skill_01JAbcdefghijklmnopqrstuvw",
138 "type": "type"
139 "type": "skill_deleted"
139140}
140141```
141142
api/beta/skills/list Changed · +55 / -38 lines
from line 10
1010
1111 Number of results to return per page.
1212
13 Maximum value is 100. Defaults to 20.
13 Ranges from `1` to `1000`. Defaults to `20`.
1414
15 default: 20
15 default: 20, minimum: 1, maximum: 1000
1616
1717- `page: optional string`
1818
from line 123
123123
124124## Returns
125125
126- `data: array of object`
126- `data: array of BetaSkill`
127127
128128 List of skills.
129129
from line 137
137137
138138 ISO 8601 timestamp of when the skill was created.
139139
140 - `display_title: string or null`
140 format: date-time
141141
142 Display title for the skill.
142 - `display_name: string`
143143
144 This is a human-readable label that is not included in the prompt sent to the model.
144 Human-readable, single-line label for the Skill. Maximum 255 characters.
145 Always set: derived from the SKILL.md frontmatter `name` when omitted at
146 creation. Not unique.
145147
146 - `latest_version: string or null`
148 - `latest_version_id: string`
147149
148 The latest version identifier for the skill.
150 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
149151
150 This represents the most recent version of the skill that has been created.
152 - `source: BetaSkillSource`
151153
152 - `source: string`
154 Where the Skill comes from.
153155
154 Source of the skill.
156 Possible values:
155157
156 This may be one of the following values:
158 * `"custom"`: authored by the platform user; private to their workspace
159 * `"anthropic"`: published by Anthropic; shared and read-only
160 * `"anthropic_example"`: Anthropic-published sample Skill
161 * `"plugin"`: resolved from an installed plugin
157162
158 * `"custom"`: the skill was created by a user
159 * `"anthropic"`: the skill was created by Anthropic
163 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
160164
161 - `type: string`
165 Where the Skill comes from.
162166
167 Possible values:
168
169 * `"custom"`: authored by the platform user; private to their workspace
170 * `"anthropic"`: published by Anthropic; shared and read-only
171 * `"anthropic_example"`: Anthropic-published sample Skill
172 * `"plugin"`: resolved from an installed plugin
173
174 - `"custom"`
175
176 - `"anthropic"`
177
178 - `"anthropic_example"`
179
180 - `"plugin"`
181
182 - `type: "skill"`
183
163184 Object type.
164185
165186 For Skills, this is always `"skill"`.
from line 191
170191
171192 ISO 8601 timestamp of when the skill was last updated.
172193
173- `has_more: boolean`
194 format: date-time
174195
175 Whether there are more results available.
176
177 If `true`, there are additional results that can be fetched using the `next_page` token.
178
179196- `next_page: string or null`
180197
181198 Token for fetching the next page of results.
from line 204
187204```bash
188205curl https://api.anthropic.com/v1/skills \
189206 -H 'anthropic-version: 2023-06-01' \
190 -H 'anthropic-beta: skills-2025-10-02' \
191207 -H "X-Api-Key: $ANTHROPIC_API_KEY"
192208```
193209
from line 215
199215 {
200216 "id": "skill_01JAbcdefghijklmnopqrstuvw",
201217 "created_at": "2024-10-30T23:58:27.427722Z",
202 "display_title": "My Custom Skill",
203 "latest_version": "1759178010641129",
204 "source": "custom",
205 "type": "type",
218 "display_name": "display_name",
219 "latest_version_id": "latest_version_id",
220 "source": {
221 "type": "custom"
222 },
223 "type": "skill",
206224 "updated_at": "2024-10-30T23:58:27.427722Z"
207225 }
208226 ],
209 "has_more": true,
210 "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
227 "next_page": "next_page"
211228}
212229```
213230
api/beta/skills/retrieve Changed · +53 / -27 lines
from line 106
106106
107107## Returns
108108
109- `id: string`
109- `BetaSkill object`
110110
111 Unique identifier for the skill.
111 - `id: string`
112112
113 The format and length of IDs may change over time.
113 Unique identifier for the skill.
114114
115- `created_at: string`
115 The format and length of IDs may change over time.
116116
117 ISO 8601 timestamp of when the skill was created.
117 - `created_at: string`
118118
119- `display_title: string or null`
119 ISO 8601 timestamp of when the skill was created.
120120
121 Display title for the skill.
121 format: date-time
122122
123 This is a human-readable label that is not included in the prompt sent to the model.
123 - `display_name: string`
124124
125- `latest_version: string or null`
125 Human-readable, single-line label for the Skill. Maximum 255 characters.
126 Always set: derived from the SKILL.md frontmatter `name` when omitted at
127 creation. Not unique.
126128
127 The latest version identifier for the skill.
129 - `latest_version_id: string`
128130
129 This represents the most recent version of the skill that has been created.
131 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
130132
131- `source: string`
133 - `source: BetaSkillSource`
132134
133 Source of the skill.
135 Where the Skill comes from.
134136
135 This may be one of the following values:
137 Possible values:
136138
137 * `"custom"`: the skill was created by a user
138 * `"anthropic"`: the skill was created by Anthropic
139 * `"custom"`: authored by the platform user; private to their workspace
140 * `"anthropic"`: published by Anthropic; shared and read-only
141 * `"anthropic_example"`: Anthropic-published sample Skill
142 * `"plugin"`: resolved from an installed plugin
139143
140- `type: string`
144 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`
141145
142 Object type.
146 Where the Skill comes from.
143147
144 For Skills, this is always `"skill"`.
148 Possible values:
145149
146 default: skill
150 * `"custom"`: authored by the platform user; private to their workspace
151 * `"anthropic"`: published by Anthropic; shared and read-only
152 * `"anthropic_example"`: Anthropic-published sample Skill
153 * `"plugin"`: resolved from an installed plugin
147154
148- `updated_at: string`
155 - `"custom"`
149156
150 ISO 8601 timestamp of when the skill was last updated.
157 - `"anthropic"`
151158
159 - `"anthropic_example"`
160
161 - `"plugin"`
162
163 - `type: "skill"`
164
165 Object type.
166
167 For Skills, this is always `"skill"`.
168
169 default: skill
170
171 - `updated_at: string`
172
173 ISO 8601 timestamp of when the skill was last updated.
174
175 format: date-time
176
152177## Example
153178
154179```bash
155180curl https://api.anthropic.com/v1/skills/$SKILL_ID \
156181 -H 'anthropic-version: 2023-06-01' \
157 -H 'anthropic-beta: skills-2025-10-02' \
158182 -H "X-Api-Key: $ANTHROPIC_API_KEY"
159183```
160184
from line 188
164188{
165189 "id": "skill_01JAbcdefghijklmnopqrstuvw",
166190 "created_at": "2024-10-30T23:58:27.427722Z",
167 "display_title": "My Custom Skill",
168 "latest_version": "1759178010641129",
169 "source": "custom",
170 "type": "type",
191 "display_name": "display_name",
192 "latest_version_id": "latest_version_id",
193 "source": {
194 "type": "custom"
195 },
196 "type": "skill",
171197 "updated_at": "2024-10-30T23:58:27.427722Z"
172198}
173199```
api/beta/skills/versions Changed · +199 / -339 lines
### Beta Deleted Skill Version ### Beta Skill Version ### Version Create Response ### Version List Response ### Version Retrieve Response ### Version Delete Response
from line 116
116116
117117### Returns
118118
119- `id: string`
119- `BetaSkillVersion object`
120120
121 Unique identifier for the skill version.
121 - `id: string`
122122
123 The format and length of IDs may change over time.
123 Unique identifier for this Skill Version. The id addresses the version in
124 paths and pins it in references.
124125
125- `created_at: string`
126 - `created_at: string`
126127
127 ISO 8601 timestamp of when the skill version was created.
128 ISO 8601 timestamp of when the skill was created.
128129
129- `description: string`
130 format: date-time
130131
131 Description of the skill version.
132 - `description: string`
132133
133 This is extracted from the SKILL.md file in the skill upload.
134 Description of the skill version.
134135
135- `directory: string`
136 This is extracted from the SKILL.md file in the skill upload.
136137
137 Directory name of the skill version.
138 - `name: string`
138139
139 This is the top-level directory name that was extracted from the uploaded files.
140 The Skill's immutable kebab-case slug, set at creation from the first
141 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
142 later upload must resolve to the same value. Also the top-level directory
143 of the Skill's mounted files and the base name of a downloaded archive.
140144
141- `name: string`
145 - `skill_id: string`
142146
143 Human-readable name of the skill version.
147 Unique identifier for the skill.
144148
145 This is extracted from the SKILL.md file in the skill upload.
149 The format and length of IDs may change over time.
146150
147- `skill_id: string`
151 - `type: "skill_version"`
148152
149 Identifier for the skill that this version belongs to.
153 Object type.
150154
151- `type: string`
155 For Skill Versions, this is always `"skill_version"`.
152156
153 Object type.
157 default: skill_version
154158
155 For Skill Versions, this is always `"skill_version"`.
156
157 default: skill_version
158
159- `version: string`
160
161 Version identifier for the skill.
162
163 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
164
165159### Example
166160
167161```bash
from line 162
168162curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
169163 -H 'Content-Type: multipart/form-data' \
170164 -H 'anthropic-version: 2023-06-01' \
171 -H 'anthropic-beta: skills-2025-10-02' \
172165 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
173166 -F files='["Example data"]'
174167```
from line 170
177170
178171```json
179172{
180 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
173 "id": "id",
181174 "created_at": "2024-10-30T23:58:27.427722Z",
182 "description": "A custom skill for doing something useful",
183 "directory": "my-skill",
184 "name": "my-skill",
175 "description": "description",
176 "name": "name",
185177 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
186 "type": "type",
187 "version": "1759178010641129"
178 "type": "skill_version"
188179}
189180```
190181
from line 197
206197
207198- `limit: optional number`
208199
209 Number of items to return per page.
200 Number of results to return per page.
210201
211 Defaults to `20`. Ranges from `1` to `1000`.
202 Ranges from `1` to `1000`. Defaults to `20`.
212203
204 default: 20, minimum: 1, maximum: 1000
205
213206- `page: optional string`
214207
215208 Optionally set to the `next_page` token from the previous response.
from line 301
308301
309302### Returns
310303
311- `data: array of object`
304- `data: array of BetaSkillVersion`
312305
313 List of skill versions.
306 List of skills.
314307
315308 - `id: string`
316309
317 Unique identifier for the skill version.
310 Unique identifier for this Skill Version. The id addresses the version in
311 paths and pins it in references.
318312
319 The format and length of IDs may change over time.
320
321313 - `created_at: string`
322314
323 ISO 8601 timestamp of when the skill version was created.
315 ISO 8601 timestamp of when the skill was created.
324316
317 format: date-time
318
325319 - `description: string`
326320
327321 Description of the skill version.
from line 322
328322
329323 This is extracted from the SKILL.md file in the skill upload.
330324
331 - `directory: string`
332
333 Directory name of the skill version.
334
335 This is the top-level directory name that was extracted from the uploaded files.
336
337325 - `name: string`
338326
339 Human-readable name of the skill version.
327 The Skill's immutable kebab-case slug, set at creation from the first
328 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
329 later upload must resolve to the same value. Also the top-level directory
330 of the Skill's mounted files and the base name of a downloaded archive.
340331
341 This is extracted from the SKILL.md file in the skill upload.
342
343332 - `skill_id: string`
344333
345 Identifier for the skill that this version belongs to.
334 Unique identifier for the skill.
346335
347 - `type: string`
336 The format and length of IDs may change over time.
348337
338 - `type: "skill_version"`
339
349340 Object type.
350341
351342 For Skill Versions, this is always `"skill_version"`.
from line 343
352343
353344 default: skill_version
354345
355 - `version: string`
356
357 Version identifier for the skill.
358
359 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
360
361- `has_more: boolean`
362
363 Indicates if there are more results in the requested page direction.
364
365346- `next_page: string or null`
366347
367 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
348 Token for fetching the next page of results.
368349
350 If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page.
351
369352### Example
370353
371354```bash
372355curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
373356 -H 'anthropic-version: 2023-06-01' \
374 -H 'anthropic-beta: skills-2025-10-02' \
375357 -H "X-Api-Key: $ANTHROPIC_API_KEY"
376358```
377359
from line 363
381363{
382364 "data": [
383365 {
384 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
366 "id": "id",
385367 "created_at": "2024-10-30T23:58:27.427722Z",
386 "description": "A custom skill for doing something useful",
387 "directory": "my-skill",
388 "name": "my-skill",
368 "description": "description",
369 "name": "name",
389370 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
390 "type": "type",
391 "version": "1759178010641129"
371 "type": "skill_version"
392372 }
393373 ],
394 "has_more": true,
395 "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
374 "next_page": "next_page"
396375}
397376```
398377
from line 391
412391
413392- `version: string`
414393
415 Version identifier for the skill.
394 Identifies the skill version by its version ID.
416395
417 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
396 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
418397
419398### Headers
420399
from line 492
513492```bash
514493curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
515494 -H 'anthropic-version: 2023-06-01' \
516 -H 'anthropic-beta: skills-2025-10-02' \
517495 -H "X-Api-Key: $ANTHROPIC_API_KEY"
518496```
519497
from line 511
533511
534512- `version: string`
535513
536 Version identifier for the skill.
514 Identifies the skill version: a version ID, or the literal `latest` for the skill's most recent version.
537515
538 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
516 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
539517
540518### Headers
541519
from line 609
631609
632610### Returns
633611
634- `id: string`
612- `BetaSkillVersion object`
635613
636 Unique identifier for the skill version.
614 - `id: string`
637615
638 The format and length of IDs may change over time.
616 Unique identifier for this Skill Version. The id addresses the version in
617 paths and pins it in references.
639618
640- `created_at: string`
619 - `created_at: string`
641620
642 ISO 8601 timestamp of when the skill version was created.
621 ISO 8601 timestamp of when the skill was created.
643622
644- `description: string`
623 format: date-time
645624
646 Description of the skill version.
625 - `description: string`
647626
648 This is extracted from the SKILL.md file in the skill upload.
627 Description of the skill version.
649628
650- `directory: string`
629 This is extracted from the SKILL.md file in the skill upload.
651630
652 Directory name of the skill version.
631 - `name: string`
653632
654 This is the top-level directory name that was extracted from the uploaded files.
633 The Skill's immutable kebab-case slug, set at creation from the first
634 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
635 later upload must resolve to the same value. Also the top-level directory
636 of the Skill's mounted files and the base name of a downloaded archive.
655637
656- `name: string`
638 - `skill_id: string`
657639
658 Human-readable name of the skill version.
640 Unique identifier for the skill.
659641
660 This is extracted from the SKILL.md file in the skill upload.
642 The format and length of IDs may change over time.
661643
662- `skill_id: string`
644 - `type: "skill_version"`
663645
664 Identifier for the skill that this version belongs to.
646 Object type.
665647
666- `type: string`
648 For Skill Versions, this is always `"skill_version"`.
667649
668 Object type.
650 default: skill_version
669651
670 For Skill Versions, this is always `"skill_version"`.
671
672 default: skill_version
673
674- `version: string`
675
676 Version identifier for the skill.
677
678 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
679
680652### Example
681653
682654```bash
683655curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
684656 -H 'anthropic-version: 2023-06-01' \
685 -H 'anthropic-beta: skills-2025-10-02' \
686657 -H "X-Api-Key: $ANTHROPIC_API_KEY"
687658```
688659
from line 661
690661
691662```json
692663{
693 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
664 "id": "id",
694665 "created_at": "2024-10-30T23:58:27.427722Z",
695 "description": "A custom skill for doing something useful",
696 "directory": "my-skill",
697 "name": "my-skill",
666 "description": "description",
667 "name": "name",
698668 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
699 "type": "type",
700 "version": "1759178010641129"
669 "type": "skill_version"
701670}
702671```
703672
from line 686
717686
718687- `version: string`
719688
720 Version identifier for the skill.
689 Identifies the skill version by its version ID.
721690
722 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
691 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").
723692
724693### Headers
725694
from line 784
815784
816785### Returns
817786
818- `id: string`
787- `BetaDeletedSkillVersion object`
819788
820 Version identifier for the skill.
789 - `id: string`
821790
822 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
791 Unique identifier for this Skill Version. The id addresses the version in
792 paths and pins it in references.
823793
824- `type: string`
794 - `type: "skill_version_deleted"`
825795
826 Deleted object type.
796 Deleted object type.
827797
828 For Skill Versions, this is always `"skill_version_deleted"`.
798 For Skill Versions, this is always `"skill_version_deleted"`.
829799
830 default: skill_version_deleted
800 default: skill_version_deleted
831801
832802### Example
833803
from line 805
835805curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
836806 -X DELETE \
837807 -H 'anthropic-version: 2023-06-01' \
838 -H 'anthropic-beta: skills-2025-10-02' \
839808 -H "X-Api-Key: $ANTHROPIC_API_KEY"
840809```
841810
from line 812
843812
844813```json
845814{
846 "id": "1759178010641129",
847 "type": "type"
815 "id": "id",
816 "type": "skill_version_deleted"
848817}
849818```
850819
851820## Domain types
852821
853### Version Create Response
822### Beta Deleted Skill Version
854823
855- `VersionCreateResponse object`
824- `BetaDeletedSkillVersion object`
856825
857826 - `id: string`
858827
859 Unique identifier for the skill version.
828 Unique identifier for this Skill Version. The id addresses the version in
829 paths and pins it in references.
860830
861 The format and length of IDs may change over time.
831 - `type: "skill_version_deleted"`
862832
863 - `created_at: string`
833 Deleted object type.
864834
865 ISO 8601 timestamp of when the skill version was created.
835 For Skill Versions, this is always `"skill_version_deleted"`.
866836
867 - `description: string`
837 default: skill_version_deleted
868838
869 Description of the skill version.
839### Beta Skill Version
870840
871 This is extracted from the SKILL.md file in the skill upload.
841- `BetaSkillVersion object`
872842
873 - `directory: string`
874
875 Directory name of the skill version.
876
877 This is the top-level directory name that was extracted from the uploaded files.
878
879 - `name: string`
880
881 Human-readable name of the skill version.
882
883 This is extracted from the SKILL.md file in the skill upload.
884
885 - `skill_id: string`
886
887 Identifier for the skill that this version belongs to.
888
889 - `type: string`
890
891 Object type.
892
893 For Skill Versions, this is always `"skill_version"`.
894
895 default: skill_version
896
897 - `version: string`
898
899 Version identifier for the skill.
900
901 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
902
903### Version List Response
904
905- `VersionListResponse object`
906
907843 - `id: string`
908844
909 Unique identifier for the skill version.
845 Unique identifier for this Skill Version. The id addresses the version in
846 paths and pins it in references.
910847
911 The format and length of IDs may change over time.
912
913848 - `created_at: string`
914849
915 ISO 8601 timestamp of when the skill version was created.
850 ISO 8601 timestamp of when the skill was created.
916851
852 format: date-time
853
917854 - `description: string`
918855
919856 Description of the skill version.
from line 857
920857
921858 This is extracted from the SKILL.md file in the skill upload.
922859
923 - `directory: string`
924
925 Directory name of the skill version.
926
927 This is the top-level directory name that was extracted from the uploaded files.
928
929860 - `name: string`
930861
931 Human-readable name of the skill version.
862 The Skill's immutable kebab-case slug, set at creation from the first
863 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
864 later upload must resolve to the same value. Also the top-level directory
865 of the Skill's mounted files and the base name of a downloaded archive.
932866
933 This is extracted from the SKILL.md file in the skill upload.
934
935867 - `skill_id: string`
936868
937 Identifier for the skill that this version belongs to.
869 Unique identifier for the skill.
938870
939 - `type: string`
940
941 Object type.
942
943 For Skill Versions, this is always `"skill_version"`.
944
945 default: skill_version
946
947 - `version: string`
948
949 Version identifier for the skill.
950
951 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
952
953### Version Retrieve Response
954
955- `VersionRetrieveResponse object`
956
957 - `id: string`
958
959 Unique identifier for the skill version.
960
961871 The format and length of IDs may change over time.
962872
963 - `created_at: string`
873 - `type: "skill_version"`
964874
965 ISO 8601 timestamp of when the skill version was created.
966
967 - `description: string`
968
969 Description of the skill version.
970
971 This is extracted from the SKILL.md file in the skill upload.
972
973 - `directory: string`
974
975 Directory name of the skill version.
976
977 This is the top-level directory name that was extracted from the uploaded files.
978
979 - `name: string`
980
981 Human-readable name of the skill version.
982
983 This is extracted from the SKILL.md file in the skill upload.
984
985 - `skill_id: string`
986
987 Identifier for the skill that this version belongs to.
988
989 - `type: string`
990
991875 Object type.
992876
993877 For Skill Versions, this is always `"skill_version"`.
994878
995879 default: skill_version
996
997 - `version: string`
998
999 Version identifier for the skill.
1000
1001 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1002
1003### Version Delete Response
1004
1005- `VersionDeleteResponse object`
1006
1007 - `id: string`
1008
1009 Version identifier for the skill.
1010
1011 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1012
1013 - `type: string`
1014
1015 Deleted object type.
1016
1017 For Skill Versions, this is always `"skill_version_deleted"`.
1018
1019 default: skill_version_deleted
1020880
api/beta/skills/versions/create Changed · +26 / -35 lines
from line 114
114114
115115## Returns
116116
117- `id: string`
117- `BetaSkillVersion object`
118118
119 Unique identifier for the skill version.
119 - `id: string`
120120
121 The format and length of IDs may change over time.
121 Unique identifier for this Skill Version. The id addresses the version in
122 paths and pins it in references.
122123
123- `created_at: string`
124 - `created_at: string`
124125
125 ISO 8601 timestamp of when the skill version was created.
126 ISO 8601 timestamp of when the skill was created.
126127
127- `description: string`
128 format: date-time
128129
129 Description of the skill version.
130 - `description: string`
130131
131 This is extracted from the SKILL.md file in the skill upload.
132 Description of the skill version.
132133
133- `directory: string`
134 This is extracted from the SKILL.md file in the skill upload.
134135
135 Directory name of the skill version.
136 - `name: string`
136137
137 This is the top-level directory name that was extracted from the uploaded files.
138 The Skill's immutable kebab-case slug, set at creation from the first
139 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every
140 later upload must resolve to the same value. Also the top-level directory
141 of the Skill's mounted files and the base name of a downloaded archive.
138142
139- `name: string`
143 - `skill_id: string`
140144
141 Human-readable name of the skill version.
145 Unique identifier for the skill.
142146
143 This is extracted from the SKILL.md file in the skill upload.
147 The format and length of IDs may change over time.
144148
145- `skill_id: string`
149 - `type: "skill_version"`
146150
147 Identifier for the skill that this version belongs to.
151 Object type.
148152
149- `type: string`
153 For Skill Versions, this is always `"skill_version"`.
150154
151 Object type.
155 default: skill_version
152156
153 For Skill Versions, this is always `"skill_version"`.
154
155 default: skill_version
156
157- `version: string`
158
159 Version identifier for the skill.
160
161 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
162
163157## Example
164158
165159```bash
from line 160
166160curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
167161 -H 'Content-Type: multipart/form-data' \
168162 -H 'anthropic-version: 2023-06-01' \
169 -H 'anthropic-beta: skills-2025-10-02' \
170163 -H "X-Api-Key: $ANTHROPIC_API_KEY" \
171164 -F files='["Example data"]'
172165```
from line 168
175168
176169```json
177170{
178 "id": "skillver_01JAbcdefghijklmnopqrstuvw",
171 "id": "id",
179172 "created_at": "2024-10-30T23:58:27.427722Z",
180 "description": "A custom skill for doing something useful",
181 "directory": "my-skill",
182 "name": "my-skill",
173 "description": "description",
174 "name": "name",
183175 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
184 "type": "type",
185 "version": "1759178010641129"
176 "type": "skill_version"
186177}
187178```
188179