---
title: "Migrate a model"
method: POST
path: "/v1/models/{modelId}/migrate"
tags: ["Models"]
---

# Migrate a model

`POST /v1/models/{modelId}/migrate`

Copy a model from one Omni connection to another by reading the source model's YAML at a specific Git ref and writing it to the target model. Supports same-organization and cross-organization migrations.

This API:

1. Reads the full model YAML from the source model's git repository at the specified `gitRef` (merged with the default branch).
2. If `branchName` is provided and the branch already exists on the target model, the API writes to that branch. If the branch doesn't exist, one is created.
3. Writes the YAML to the target model or branch, replacing its model definition.

### Requirements

To successfully migrate a model:

- The user performing the migration must have:
   - **For the source model** - **Querier**, **Modeler**, or **Connection Admin** permissions 
   - **For the target model** - **Modeler** or **Connection Admin** permissions
   - **For cross-organization migrations** - The user must be a member of both organizations
- The source model must have [git configured](/integrations/git). This is required so the API can read the model YAML from the repository.
- The target model should have an identical schema model to the source model at the instant the git ref was committed.

## Path parameters

- `modelId` string, uuid, required

## Request body

- object
  - `gitRef` string, required — Git reference (branch name, tag, or commit SHA) to read the source model YAML from.
  - `targetModelId` string, uuid, required — The shared model ID to write the YAML to.
  - `branchName` string — **Required if the target model has git enabled.**. Branch name on the target model. If the branch doesn't exist, it will be created.
  - `commitMessage` string — Git commit message.
  - `deleteViewsAndTopicsMissingFromSource` boolean — Controls how views and topics present in the target model but missing from the source model are handled. When `true` (default), these views and topics are marked as `ignored: true`. When `false`, they are inherited from the parent model instead.

## Response `200`

Model migrated successfully

- object
  - `success` boolean — Whether the migration completed successfully.

## Other responses

- `400` — Bad Request Possible error messages: - `Bad Request: Invalid JSON body` - `Bad Request: gitRef is empty` - `Bad Request: targetModelId is not a valid UUID` - `Bad Request: Target model has git enabled but branchName was not provided`
- `401` — Missing or invalid authentication
- `403` — Forbidden Possible error messages: - `Forbidden: User does not have access to the source or target model`
- `404` — Not Found Possible error messages: - `Not Found: Source model not found` - `Not Found: Target model not found`
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)