{"slug": "sonnet-5-5-api-migration-update-more-than-the-model-id", "title": "Sonnet 5.5 API Migration: Update More Than the Model ID", "summary": "The Tokenhot Team published a migration checklist for moving native Messages API integrations to Anthropic's Claude Sonnet 5.5, warning that changing only the model ID leaves inherited settings in place. The guide advises capturing a redacted outgoing request as a baseline, then separately auditing the request, the response parsing, and user outcomes, and flags that non-default temperature, top_p and top_k values are rejected, manual thinking budgets must give way to adaptive thinking or the between_tools mode, and assistant prefill must move into the prompt or output schema. The team notes its JSON and checker have offline validation only, with live Claude and Tokenhot compatibility still unverified.", "body_md": "*Originally published by [Tokenhot Team](https://tokenhot.ai/blog/sonnet-5-5-api-migration) on 2026-10-10. The DEV edition was formatted with AI assistance.*\n\nChanging 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.\n\nThis guide targets ordinary **native Messages API** integrations: text requests, client tools and structured output. It follows Anthropic's current [Sonnet 5.5 migration guide](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide), and identifies the checks needed for our gateway. 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.\n\nThe supplied JSON and checker have offline validation only. Live Claude and Tokenhot compatibility remain unverified; use the requests as candidates for your route tests.\n\nCapture 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.\n\nUse 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.\n\n| Earlier request or assumption | Sonnet 5.5 migration action | \n|---|---|\n| Earlier Sonnet model code | Use the exact new code for the selected provider. The native Claude API ID is `claude-sonnet-5-5` . | \n| Manual `thinking.type: enabled` and`budget_tokens` | Remove the budget and choose adaptive thinking plus an effort level. | \n| Inherited `temperature` ,`top_p` or`top_k` | Remove these from the minimal profile; non-default values are rejected. | \n| Last-message assistant prefill | Move the instruction into an appropriate prompt or supported output schema. | \n| Raw `output_format` | Prefer `output_config.format` ; do not confuse this with an SDK helper's argument. | \n\nThese 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.\n\nSonnet 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](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting).\n\nFor example, this is a **historical-shaped configuration fragment**, not a request to send:\n\n```\n{\n  \"model\": \"claude-sonnet-5\",\n  \"thinking\": {\"type\": \"disabled\"},\n  \"output_config\": {\"effort\": \"xhigh\"}\n}\n```\n\nA candidate Sonnet 5.5 request without up-front thinking is:\n\n```\n{\n  \"model\": \"claude-sonnet-5-5\",\n  \"max_tokens\": 1024,\n  \"thinking\": {\"type\": \"between_tools\"},\n  \"output_config\": {\"effort\": \"medium\"},\n  \"messages\": [\n    {\"role\": \"user\", \"content\": \"List three checks before deploying an API client. Keep each check to one sentence.\"}\n  ]\n}\n```\n\nSave 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.\n\nThe 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](https://platform.claude.com/docs/en/build-with-claude/effort) describes the setting; your regression results determine whether the chosen level is sufficient.\n\nSonnet 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](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5).\n\nWhere 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](https://platform.claude.com/docs/en/build-with-claude/structured-outputs). 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.\n\nTest 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.\n\nThe existing [tool-result ordering guide](https://tokenhot.ai/blog/claude-tool-result-ordering) covers pairing and continuation. Reuse that process rather than rebuilding a second ordering implementation for this version migration.\n\nDo not assume the first content block is text. Preserve the original response for conversation replay, then derive a separate display string:\n\n``` python\ndef display_text(response):\n    \"\"\"Display extraction only: not a completion or conversation validator.\"\"\"\n    blocks = response.get(\"content\", [])\n    if not isinstance(blocks, list):\n        raise ValueError(\"Expected content blocks\")\n    return \"\\n\".join(\n        block[\"text\"]\n        for block in blocks\n        if isinstance(block, dict)\n        and block.get(\"type\") == \"text\"\n        and isinstance(block.get(\"text\"), str)\n    )\n```\n\nThat 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.\n\nAn 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](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5) explain that distinction. Do not “repair” a display issue by editing signatures or reconstructing the assistant turn. Use the existing [signature diagnostic guide](https://tokenhot.ai/blog/claude-invalid-signature-thinking-block) for a real replay failure, together with the current model's conditions.\n\nOur [Sonnet 5.5 reference](https://docs.tokenhot.ai/claude-sonnet-5-5) 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.\n\nThe 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:\n\n| Evidence | What it establishes | \n|---|---|\n| Model listing and basic endpoint example | A documented entry point | \n| Source-code field or passthrough support | An implementation path in a particular code revision | \n| Successful authorized request on your route | Acceptance of that request, for that account and time | \n| Regression suite and reconciled account record | Broader workload behavior and observed cost within the test scope | \n\nDo 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.\n\nDownload the candidate request files: [between-tools JSON](https://tokenhot.ai/downloads/blog/sonnet-5-5-api-migration/2026-10-10/sonnet-between-tools.json) and [adaptive JSON](https://tokenhot.ai/downloads/blog/sonnet-5-5-api-migration/2026-10-10/sonnet-adaptive.json).\n\nThe companion [sonnet_request_check.py](https://tokenhot.ai/downloads/blog/sonnet-5-5-api-migration/2026-10-10/sonnet_request_check.py) only inspects raw JSON. Run:\n\n```\npython sonnet_request_check.py sonnet-between-tools.json\n```\n\nAn 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.\n\nFor separately authorized route tests, keep one row for each of these obligations:\n\n| Case | Acceptance criterion | \n|---|---|\n| Minimal text | Expected answer, usable text extraction and a correctly handled stop reason | \n| Chosen thinking profile | Request accepted and the caller handles all returned block types | \n| Client tool | Correct selection, valid arguments, matching result and final answer | \n| Structured output | Declared fields and types validate, or the unsupported capability is recorded | \n| Continued conversation | Earlier content remains intact; new turns do not silently rewrite history | \n| Controlled failure | Request ID and failure stage retained; no blind repetition of side effects | \n\nRecord 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.", "url": "https://wpnews.pro/news/sonnet-5-5-api-migration-update-more-than-the-model-id", "canonical_source": "https://dev.to/por_ty_35eac5b9bfc8b95909/sonnet-55-api-migration-update-more-than-the-model-id-4kib", "published_at": "2026-11-20 03:05:22+00:00", "updated_at": "2026-11-20 03:13:07.177199+00:00", "lang": "en", "topics": ["large-language-models", "ai-tools", "developer-tools", "ai-products"], "entities": ["Anthropic", "Claude Sonnet 5.5", "Tokenhot", "Claude Messages API", "Claude Managed Agents"], "also_reported_by": [], "takeaway": "Migrating to claude-sonnet-5-5 requires removing inherited temperature, top_p and top_k values, replacing manual thinking budgets with adaptive or between_tools thinking plus an explicit effort level, and moving assistant prefill into the prompt or output schema.", "recommendation": {"advice": "Capture a redacted outgoing request after SDK defaults and middleware apply, then diff it against the Sonnet 5.5 field map before switching model IDs.", "playbook": "production-ops", "playbook_url": "https://wpnews.pro/playbooks/production-ops"}, "alternates": {"html": "https://wpnews.pro/news/sonnet-5-5-api-migration-update-more-than-the-model-id", "markdown": "https://wpnews.pro/news/sonnet-5-5-api-migration-update-more-than-the-model-id.md", "text": "https://wpnews.pro/news/sonnet-5-5-api-migration-update-more-than-the-model-id.txt", "jsonld": "https://wpnews.pro/news/sonnet-5-5-api-migration-update-more-than-the-model-id.jsonld"}}