> 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.

# Migrations API

> Reference for the Migrations API: create migrations linked to an eval suite, read the eval gate and shadow comparison, tune the sample rate, and complete by rewriting selected routing policies.

The Migrations API drives the [model migration lifecycle](/merge-gateway/evals/model-migrations) from code: link a migration to an eval suite, shadow the candidate on live traffic while you read the comparison, then complete by rewriting the routing policies you select.

## Base URL and authentication

```text
https://api-gateway.merge.dev
```

Authenticate with the `mg_` API key you send `/v1/responses` with. The organization comes from the key; customer API keys are rejected.

```http
Authorization: Bearer mg_...
```

> **Warning**
>
> Any active organization API key can drive the full lifecycle, including completion, so treat automation keys like deploy credentials.

## Reference

| Endpoints                                                                              | What they do                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`, `POST /v1/migrations`                                                           | List migrations, or create one from `baseline_model`, `candidate_model`, and a required `experiment_suite_id`                                                                                                                                           |
| `GET`, `PATCH /v1/migrations/{migration_id}`                                           | Read or change a migration. Each `PATCH` carries exactly one action: a `status` change, an `experiment_suite_id` (`null` unlinks), or a `shadow_sample_rate` above 0 and up to 1.                                                                       |
| `GET .../events`, `.../comparison`, `.../comparison/requests`, `.../affected-policies` | The event trail, the baseline-versus-candidate comparison and its sampled requests, and the policies a completion would rewrite                                                                                                                         |
| `POST .../complete`                                                                    | Rewrite the routing policies in `policy_ids` (up to 50) from baseline to candidate. An empty list completes without changing traffic. Add an `override_note` when completing against a failing eval verdict, since the verdict never blocks completion. |
| `POST .../abandon`                                                                     | Abandon the migration                                                                                                                                                                                                                                   |

Requests that name the baseline model directly are never rewritten. To revert a completed migration, `PATCH` its `status` to `reverted`: Gateway restores the rewritten policies, skipping any edited since the cutover. See the [error codes worth branching on](/merge-gateway/errors#management-and-platform-apis).

## Next steps

#### [Model migrations](/merge-gateway/evals/model-migrations)

Plan and evaluate a model migration

#### [Run evaluations](/merge-gateway/evals/running-evals)

Run evaluations against your suite