Sonnet 5.5 API Migration: Update More Than the Model ID

Changing a request to claude-sonnet-5-5 does not remove settings inherited from an earlier model. A useful migration checks three things separately: the request you send, the response your application understands, and the outcome your users need.

This guide targets ordinary native Messages API integrations: text requests, client tools and structured output. It follows Anthropic's current Sonnet 5.5 migration guide, with a separate Tokenhot verification boundary. It does not cover a complete computer-use or advisor migration. Claude Managed Agents has different migration requirements, so do not apply this checklist blindly to that product.

The supplied JSON and local checker were checked offline, not through a live Claude or Tokenhot account. Treat the requests as candidates for your route tests, not evidence that those tests have passed.

Start with the request your application actually sends

Capture one redacted outgoing request after SDK defaults, client presets and middleware have been applied. Record its model, protocol, endpoint, SDK version and any beta headers. A configuration screen can say “adaptive” while another layer still inserts an old budget or sampling setting.

Use that capture as the baseline for the following field map. Keep the original as a separate file: changing it in place makes it harder to tell whether a later failure comes from the model change or a second configuration edit.

Earlier request or assumption	Sonnet 5.5 migration action
Earlier Sonnet model code	Use the exact new code for the selected provider. The native Claude API ID is claude-sonnet-5-5.
Manual thinking.type: enabled and budget_tokens	Remove the budget and choose adaptive thinking plus an effort level.
Inherited temperature, top_p or top_k	Remove these from the minimal profile; non-default values are rejected.
Last-message assistant prefill	Move the instruction into an appropriate prompt or supported output schema.
Raw output_format	Prefer output_config.format; do not confuse this with an SDK helper's argument.

These changes depend on the starting model. A migration from Sonnet 4.5 has more legacy behavior to remove than one from Sonnet 5. The official guide also lists additional computer-use, tool-version and beta-header changes; use those sections for integrations outside this article's scope.

Choose a thinking profile deliberately

Sonnet 5.5 defaults to adaptive thinking. To avoid up-front thinking, the documented alternative is between_tools, not the older disabled setting. This mode accepts effort low, medium or high, and its thinking object must contain only type. Do not attach display, a budget or binding controls. Do not change effort mid-conversation in that mode. These constraints are explicit in the thinking troubleshooting guide.

For example, this is a historical-shaped configuration fragment, not a request to send:

{
  "model": "claude-sonnet-5",
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}

A candidate Sonnet 5.5 request without up-front thinking is:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "medium"},
  "messages": [
    {"role": "user", "content": "List three checks before deploying an API client. Keep each check to one sentence."}
  ]
}

Save that as sonnet-between-tools.json. For an adaptive candidate, replace the thinking object with {"type":"adaptive"}. Keep effort explicit so that a later run does not silently use a different default.

The output cap in this example is a test choice, not a recommended production limit. Reassess it against your expected answer and thinking usage. Likewise, effort is a workload control, not a conversion formula for an old token budget. Anthropic's effort guide describes the setting; your regression results determine whether the chosen level is sufficient.

Separate tool selection from valid tool arguments

Sonnet 5.5 rejects forced tool_choice types any and tool. Replacing them with auto changes application behavior: the model may return text instead of a call. A prompt can explain when the tool is required, but your application still needs a branch for “no tool call.” See what changed in Sonnet 5.5.

Where the selected platform supports it, strict: true constrains a tool's arguments. It does not force the tool to run. The schema belongs in the tool definition, with the restrictions documented under structured outputs and strict tool use. Do not copy a strict-tool setting to a route whose platform does not support it; the migration guide specifically calls out the Sonnet 5.5 Bedrock exception.

Test tool selection and argument validity as two acceptance criteria. A valid JSON answer is not a successful tool round trip when the application needed a lookup. Conversely, an API rejection is not evidence that your tool implementation failed—it may never have been invoked.

The existing tool-result ordering guide covers pairing and continuation. Reuse that process rather than rebuilding a second ordering implementation for this version migration.

Parse response blocks, not a fixed position

Do not assume the first content block is text. Preserve the original response for conversation replay, then derive a separate display string:

def display_text(response):
    """Display extraction only: not a completion or conversation validator."""
    blocks = response.get("content", [])
    if not isinstance(blocks, list):
        raise ValueError("Expected content blocks")
    return "\n".join(
        block["text"]
        for block in blocks
        if isinstance(block, dict)
        and block.get("type") == "text"
        and isinstance(block.get("text"), str)
    )

That function does not discard the original content array, execute tools, or declare the request successful. Your caller must still inspect the stop reason and route tool calls or incomplete outcomes to the appropriate branch.

An empty thinking field is not necessarily a broken response. Sonnet 5.5's default display can omit its text while preserving signed blocks, and progress notes may appear in thinking blocks rather than ordinary text. The model's response-change notes explain that distinction. Do not “repair” a display issue by editing signatures or reconstructing the assistant turn. Use the existing signature diagnostic guide for a real replay failure, together with the current model's conditions.

What is established for Tokenhot—and what still needs a route test

The Tokenhot Sonnet 5.5 reference documents Bearer authentication, POST https://api.tokenhot.ai/v1/messages, and the request model claude-sonnet-5-5. Its displayed response example still names an older Sonnet model. That inconsistency is not proof that a real request is misrouted, and it must not be used to infer an alias mapping.

The reference's basic example does not certify every native thinking, strict-tool or beta feature. Before changing a production route, ask for or obtain evidence for the exact configuration your application needs. At minimum, distinguish:

Evidence	What it establishes
Model listing and basic endpoint example	A documented entry point
Source-code field or passthrough support	An implementation path in a particular code revision
Successful authorized request on your route	Acceptance of that request, for that account and time
Regression suite and reconciled account record	Broader workload behavior and observed cost within the test scope

Do not send a Messages JSON body to an OpenAI-shaped endpoint merely because both expose the same model label. A translated route needs its own parameter and response checks.

Run the local checklist, then a small regression matrix

Download the candidate request files: between-tools JSON and adaptive JSON.

The companion sonnet_request_check.py only inspects raw JSON. Run:

python sonnet_request_check.py sonnet-between-tools.json

An empty items_to_review list means the small local checklist found none of its known patterns. It does not validate every field, a signed history, an SDK serialization path or remote support. The checker intentionally reports sampling fields for review even when a default value might be accepted; its output is not a prediction that every flagged request returns 400.

For separately authorized route tests, keep one row for each of these obligations:

Case	Acceptance criterion
Minimal text	Expected answer, usable text extraction and a correctly handled stop reason
Chosen thinking profile	Request accepted and the caller handles all returned block types
Client tool	Correct selection, valid arguments, matching result and final answer
Structured output	Declared fields and types validate, or the unsupported capability is recorded
Continued conversation	Earlier content remains intact; new turns do not silently rewrite history
Controlled failure	Request ID and failure stage retained; no blind repetition of side effects

Record actual elapsed time, attempts and billed usage rather than comparing response length alone. Preserve the old route for a deliberate rollback decision, not an automatic retry on every failure. The migration is ready when these application obligations are satisfied—not merely when one HTTP request returns 200.