> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Move an existing integration to Gateway

> Choose the Gateway endpoint for your client, map model IDs and routing, verify agent behavior, and move traffic in stages.

Most integrations move to Gateway with a new base URL and API key. Before production traffic moves, check model IDs, routing behavior, and any request or response fields your agent depends on.

> **Use the Claude Code migration skills**
>
> Install the [Merge Gateway skills](/merge-gateway/install-skills), then ask Claude Code to inspect your current gateway or provider SDK and migrate the integration. It selects an applicable migration skill and helps map endpoints, model IDs, and settings.

## Choose the matching endpoint

Keep your current SDK and use the Gateway endpoint for its wire format. See the [base URL table](/merge-gateway/get-started#other-sdks) for supported clients.

OpenAI Responses clients need `https://api-gateway.merge.dev/v1/openai`. The native `https://api-gateway.merge.dev/v1/responses` endpoint accepts a similar request body but returns a different streaming event format. Codex clients are detected and redirected automatically.

## Map model IDs and routing

Gateway model IDs use `provider/model`, where the provider is the model's direct creator, such as `anthropic/claude-sonnet-5-5` or `openai/gpt-5.5`. List available models with `GET /v1/models`; check each model's `vendors` when you require a particular host, region, or [zero data retention](/merge-gateway/security/zero-data-retention).

Use full model IDs to avoid ambiguity. OpenAI-compatible endpoints resolve bare names such as `gpt-5.5`; the native API rejects a name that matches more than one provider.

Move model selection and fallback behavior into a [routing policy](/merge-gateway/routing/overview), then send its [model alias](/merge-gateway/routing/model-aliases) as `model`. Update the policy without deploying application code.

| Current behavior             | Gateway option                                                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Default model with fallbacks | Priority policy, selected with its alias                                                                         |
| Per-request fallback list    | `priority_order` with up to 10 models and optional vendor pins                                                   |
| Provider order or allow-list | Vendor pins on policy entries, or [vendor and region restrictions](/merge-gateway/security/geo-location-routing) |
| Cost or quality routing      | [Intelligent policy](/merge-gateway/routing/intelligent)                                                         |

Gateway retries eligible vendor failures, but not invalid requests or credential rejections. See [failover behavior](/merge-gateway/routing/using-policies#failover).

## Verify the behavior your agent needs

* **Tool calls:** return the full assistant turn, including tool-call and reasoning blocks, with the tool results. See [tool calling](/merge-gateway/capabilities/tool-calling).
* **Streaming:** confirm the selected endpoint emits the events your client parses. See [streaming](/merge-gateway/streaming).
* **Structured outputs and reasoning:** support varies by model and vendor. Check the route in the [model catalog](/merge-gateway/models/catalog).
* **Tags and metadata:** define each tag key and value for your organization before sending it. For tag-based routing, include the pairs in the request's `tags` body field and configure rules on a project's **Routing** tab. The native Responses API rejects undefined pairs.
* **Request fields:** fields specific to your current gateway may be ignored or rejected. Map each one to a Gateway feature or remove it.

## Cut over in stages

1. Record the models, fallbacks, request fields, and response parsing your application relies on
2. Point a staging environment at Gateway and run your existing evals, or compare models with [Gateway evals](/merge-gateway/evals/overview)
3. Compare errors, latency, selected routes, and `usage.cost` in Gateway logs
4. Move a small share of production traffic, then expand once the results match

Keep the previous configuration deployable until the rollout is complete so you can switch back if a model or behavior is missing.

## Next steps

#### [Get started](/merge-gateway/get-started)

Send a first request with your current SDK

#### [Routing policies](/merge-gateway/routing/overview)

Recreate model selection and failover

#### [Coding agents](/merge-gateway/coding-agents/overview)

Configure a supported coding agent