Move an existing integration to Gateway

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.

Choose the matching endpoint

Keep your current SDK and use the Gateway endpoint for its wire format. See the base URL table 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.

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, then send its model alias as model. Update the policy without deploying application code.

Gateway retries eligible vendor failures, but not invalid requests or credential rejections. See failover behavior.

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.
• Streaming: confirm the selected endpoint emits the events your client parses. See streaming.
• Structured outputs and reasoning: support varies by model and vendor. Check the route in the model 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
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