# name: claude-api-toolkit description: 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. license: MIT compatibility: Scripts need Node.js 20+. No network access and no API key are required by the scripts. metadata: version: "1.0.1" observed: "2026-11-10"

# Claude API toolkit

Rules for Claude models changed sharply between generations. Parameters that worked a year ago (budget_tokens, temperature, forced tool_choice, assistant prefill) now return HTTP 400 on current models. Do not write Claude API code from memory. Use the tables and the linter in this skill: they were produced by sending real requests to every model and recording the answers.

# The loop to follow

Pick the model from references/models.md (or node scripts/claude-api.mjs models). Default to claude-opus-5-5; use claude-sonnet-5-5 for speed/cost balance, claude-haiku-5-5 for high-volume simple work, claude-fable-5-2 for the hardest long-running tasks. Use the model the user names if they name one. Never invent an id or add a date suffix.

Build the request, then lint it before running anything:

bash

node scripts/claude-api.mjs lint request.json      # exit 2 = the API would reject it
node scripts/claude-api.mjs fix request.json       # corrected request + what changed

Lint again after every change of model. Each finding carries the fix and the API's own error text.

Start from a scaffold rather than a blank file:
bash
```
node scripts/claude-api.mjs scaffold manual_loop --language python --model claude-opus-5-5
```
Approaches: single_call, streaming, structured_output, manual_loop, tool_runner, batch, managed_agent. Every template has been executed against the live API.
Use the official SDK (@anthropic-ai/sdk, anthropic), not hand-rolled HTTP, and read the key from ANTHROPIC_API_KEY. Never put a key in source, logs or prompts.
Check stop_reason before reading content — every time. See "Stop reasons" below.
Estimate cost when volume matters: node scripts/claude-api.mjs cost <model> <in> <out>.

# Rules that cause most failures

Details and per-model tables: references/request-rules.md.

Thinking. Use thinking: {"type": "adaptive"}. budget_tokens is rejected by every model from Opus 4.7 / Sonnet 5 / Haiku 5.5 on; only the 4.5 models need {"type": "enabled", "budget_tokens": N}. Thinking cannot be turned off on Fable 5.x and Opus 5.5 — omit the field and lower effort. Sonnet 5.5 takes {"type": "between_tools"} instead of disabled.
Effort goes in output_config: {"effort": ...}, never top-level. Set it explicitly; defaults differ by model. Not every model has every level (4.6 has no xhigh; Sonnet 4.5 / Haiku 4.5 have no effort at all).
Sampling. temperature, top_p, top_k are rejected on every model under API version 2026-10-21, which current SDKs send. Remove them.
Forced tool choice (any, tool) is rejected by Fable 5.1/5.2, Opus 5.5, Sonnet 5.5. Use auto, name the tool in the prompt, add strict: true to the tool. If the forced call only existed to get JSON, use structured outputs.
Prefill (ending messages with an assistant turn) is rejected by every model from 4.6 on.
Structured outputs are output_config: {"format": {"type": "json_schema", "schema": ...}} with additionalProperties: false on objects. output_format is deprecated.
max_tokens is required. Cap: 128K (64K on the 4.5 models). Above ~21K, stream.
Beta features need their flag in betas and the beta endpoint: task budgets, compaction, context editing, server-side fallbacks, MCP connector. fix adds the right flag.

# Stop reasons

`stop_reason`	Meaning	What to do
`end_turn`	Finished	Read the content
`tool_use`	Wants tool results	Run every `tool_use` block; return all `tool_result` blocks in one user message
`max_tokens`	Truncated	Raise `max_tokens` or continue; truncated JSON is invalid
`pause_turn`	A server tool paused	Resend the conversation unchanged to resume
`refusal`	Declined (HTTP 200)	Read `stop_details`; do not treat content as an answer
`stop_sequence`	Hit a stop sequence	Read the content

Append the whole assistant content array to history (thinking and tool-use blocks included), never just the text.

# Choosing how to build

Need	Use	Reference
One answer, classification, extraction	Single call (+ structured output)	`references/requests.md`
Live text in a UI, long output	Streaming	`references/requests.md`
Your own tools, full control	Manual tool loop	`references/tools-and-agents.md`
Your own tools, less code	SDK tool runner (beta helper)	`references/tools-and-agents.md`
Anthropic runs the loop and a sandbox	Managed Agents (beta)	`references/managed-agents.md`
Thousands of non-urgent requests	Message Batches (half price)	`references/requests.md`
Long conversations, cost, caching	Caching and context tools	`references/caching-and-context.md`
A 4xx/5xx or odd behaviour	Error table	`references/errors.md`

Prefer the simplest tier that works. Most tasks need one call or a fixed workflow, not an agent.

# Migrating code to a newer model

bash

node scripts/claude-api.mjs migrate request.json claude-opus-5-5

Then, by hand: re-tune effort (levels were recalibrated between generations), loosen prompts written for older models (they are often too prescriptive), re-count tokens (tokenizers differ), re-run your evaluation. Ask the user which files are in scope before editing a codebase.

# Honesty about this skill's limits

The tables are a snapshot (see metadata.observed), taken under API version 2026-10-21. If the API disagrees with a table, the API is right: trust the error, and tell the user the skill is stale.
Models the probing key could not see are absent; the linter calls them unknown rather than guess.
Not probed: computer use, the advisor tool, memory stores, message threads, thinking-block replay rules, and differences on Amazon Bedrock, Google Vertex AI and Microsoft Foundry. For those, read the official documentation at https://platform.claude.com/docs.
Cost output is an estimate from list prices.

The companion MCP server @spboucher/claude-api-mcp exposes the same linter plus live tools (messages, token counting, batches, files, Managed Agents).

spb llm-api-toolkits