Migrations API

The Migrations API drives the model migration lifecycle 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

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.

Authorization: Bearer mg_...

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.

Next steps

Model migrations

Plan and evaluate a model migration

Run evaluations

Run evaluations against your suite