Repository Public Research preview
1---2name: claude-api-toolkit3description: Write, review, debug and migrate code that calls the Claude API (Anthropic Messages API, tools, structured outputs, streaming, batches, files, Managed Agents). Use when choosing a Claude model, building a request or an agent, fixing a 400 error, estimating cost, or moving code to a newer model. Ships a linter and model tables built from live API probes.4license: MIT5compatibility: Scripts need Node.js 20+. No network access and no API key are required by the scripts.6metadata:7 version: "1.0.1"8 observed: "2026-11-10"9---1011# Claude API toolkit1213Rules for Claude models changed sharply between generations. Parameters that worked a year ago14(`budget_tokens`, `temperature`, forced `tool_choice`, assistant prefill) now return HTTP 400 on15current models. **Do not write Claude API code from memory.** Use the tables and the linter in this16skill: they were produced by sending real requests to every model and recording the answers.1718## The loop to follow19201. **Pick the model** from `references/models.md` (or `node scripts/claude-api.mjs models`).21 Default to `claude-opus-5-5`; use `claude-sonnet-5-5` for speed/cost balance, `claude-haiku-5-5`22 for high-volume simple work, `claude-fable-5-2` for the hardest long-running tasks. Use the23 model the user names if they name one. Never invent an id or add a date suffix.242. **Build the request**, then **lint it before running anything**:25 ```bash26 node scripts/claude-api.mjs lint request.json # exit 2 = the API would reject it27 node scripts/claude-api.mjs fix request.json # corrected request + what changed28 ```29 Lint again after every change of model. Each finding carries the fix and the API's own error text.303. **Start from a scaffold** rather than a blank file:31 ```bash32 node scripts/claude-api.mjs scaffold manual_loop --language python --model claude-opus-5-533 ```34 Approaches: `single_call`, `streaming`, `structured_output`, `manual_loop`, `tool_runner`,35 `batch`, `managed_agent`. Every template has been executed against the live API.364. **Use the official SDK** (`@anthropic-ai/sdk`, `anthropic`), not hand-rolled HTTP, and read the37 key from `ANTHROPIC_API_KEY`. Never put a key in source, logs or prompts.385. **Check `stop_reason` before reading content** — every time. See "Stop reasons" below.396. **Estimate cost** when volume matters: `node scripts/claude-api.mjs cost <model> <in> <out>`.4041## Rules that cause most failures4243Details and per-model tables: `references/request-rules.md`.4445- **Thinking.** Use `thinking: {"type": "adaptive"}`. `budget_tokens` is rejected by every model46 from Opus 4.7 / Sonnet 5 / Haiku 5.5 on; only the 4.5 models need47 `{"type": "enabled", "budget_tokens": N}`. Thinking cannot be turned off on Fable 5.x and48 Opus 5.5 — omit the field and lower effort. Sonnet 5.5 takes `{"type": "between_tools"}` instead49 of `disabled`.50- **Effort** goes in `output_config: {"effort": ...}`, never top-level. Set it explicitly; defaults51 differ by model. Not every model has every level (4.6 has no `xhigh`; Sonnet 4.5 / Haiku 4.5 have52 no effort at all).53- **Sampling.** `temperature`, `top_p`, `top_k` are rejected on every model under API version54 `2026-10-21`, which current SDKs send. Remove them.55- **Forced tool choice** (`any`, `tool`) is rejected by Fable 5.1/5.2, Opus 5.5, Sonnet 5.5. Use56 `auto`, name the tool in the prompt, add `strict: true` to the tool. If the forced call only57 existed to get JSON, use structured outputs.58- **Prefill** (ending `messages` with an assistant turn) is rejected by every model from 4.6 on.59- **Structured outputs** are `output_config: {"format": {"type": "json_schema", "schema": ...}}`60 with `additionalProperties: false` on objects. `output_format` is deprecated.61- **`max_tokens`** is required. Cap: 128K (64K on the 4.5 models). Above ~21K, stream.62- **Beta features need their flag** in `betas` and the beta endpoint: task budgets, compaction,63 context editing, server-side fallbacks, MCP connector. `fix` adds the right flag.6465## Stop reasons6667| `stop_reason` | Meaning | What to do |68|---|---|---|69| `end_turn` | Finished | Read the content |70| `tool_use` | Wants tool results | Run every `tool_use` block; return all `tool_result` blocks in **one** user message |71| `max_tokens` | Truncated | Raise `max_tokens` or continue; truncated JSON is invalid |72| `pause_turn` | A server tool paused | Resend the conversation unchanged to resume |73| `refusal` | Declined (HTTP 200) | Read `stop_details`; do not treat content as an answer |74| `stop_sequence` | Hit a stop sequence | Read the content |7576Append the **whole** assistant `content` array to history (thinking and tool-use blocks included),77never just the text.7879## Choosing how to build8081| Need | Use | Reference |82|---|---|---|83| One answer, classification, extraction | Single call (+ structured output) | `references/requests.md` |84| Live text in a UI, long output | Streaming | `references/requests.md` |85| Your own tools, full control | Manual tool loop | `references/tools-and-agents.md` |86| Your own tools, less code | SDK tool runner (beta helper) | `references/tools-and-agents.md` |87| Anthropic runs the loop and a sandbox | Managed Agents (beta) | `references/managed-agents.md` |88| Thousands of non-urgent requests | Message Batches (half price) | `references/requests.md` |89| Long conversations, cost, caching | Caching and context tools | `references/caching-and-context.md` |90| A 4xx/5xx or odd behaviour | Error table | `references/errors.md` |9192Prefer the simplest tier that works. Most tasks need one call or a fixed workflow, not an agent.9394## Migrating code to a newer model9596```bash97node scripts/claude-api.mjs migrate request.json claude-opus-5-598```99100Then, by hand: re-tune `effort` (levels were recalibrated between generations), loosen prompts101written for older models (they are often too prescriptive), re-count tokens (tokenizers differ),102re-run your evaluation. Ask the user which files are in scope before editing a codebase.103104## Honesty about this skill's limits105106- The tables are a **snapshot** (see `metadata.observed`), taken under API version `2026-10-21`.107 If the API disagrees with a table, the API is right: trust the error, and tell the user the108 skill is stale.109- Models the probing key could not see are absent; the linter calls them unknown rather than guess.110- Not probed: computer use, the advisor tool, memory stores, message threads, thinking-block replay111 rules, and differences on Amazon Bedrock, Google Vertex AI and Microsoft Foundry. For those, read112 the official documentation at `https://platform.claude.com/docs`.113- Cost output is an estimate from list prices.114115The companion MCP server `@spboucher/claude-api-mcp` exposes the same linter plus live tools116(messages, token counting, batches, files, Managed Agents).117