> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/merge-gateway/migrations-api/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

> Build once. Connect to every API, tool, and LLM. Ship products and agents to production without owning the integration stack.


## API Docs

- Migrations API > Migrations [List migrations](https://docs.merge.dev/merge-gateway/migrations-api/migrations/list-migrations.md)
- Migrations API > Migrations [Create migration](https://docs.merge.dev/merge-gateway/migrations-api/migrations/create-migration.md)
- Migrations API > Migrations [Get migration](https://docs.merge.dev/merge-gateway/migrations-api/migrations/get-migration.md)
- Migrations API > Migrations [Update migration](https://docs.merge.dev/merge-gateway/migrations-api/migrations/update-migration.md)
- Migrations API > Migrations [Abandon migration](https://docs.merge.dev/merge-gateway/migrations-api/migrations/abandon-migration.md)
- Migrations API > Migrations [Get affected policies](https://docs.merge.dev/merge-gateway/migrations-api/migrations/get-affected-policies.md)
- Migrations API > Migrations [Get shadow comparison](https://docs.merge.dev/merge-gateway/migrations-api/migrations/get-shadow-comparison.md)
- Migrations API > Migrations [List compared requests](https://docs.merge.dev/merge-gateway/migrations-api/migrations/list-compared-requests.md)
- Migrations API > Migrations [Complete migration](https://docs.merge.dev/merge-gateway/migrations-api/migrations/complete-migration.md)
- Migrations API > Migrations [List migration events](https://docs.merge.dev/merge-gateway/migrations-api/migrations/list-migration-events.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.merge.dev/openapi.json)
- [OpenAPI YAML](https://docs.merge.dev/openapi.yaml)