> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/models/migrate-a-model",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Migrate a model
> Copies 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.
## OpenAPI
````yaml /api/openapi.yaml post /v1/models/{modelId}/migrate
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/models/{modelId}/migrate:
post:
tags:
- Models
summary: Migrate a model
description: >
Copies 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.
operationId: migrateModel
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The shared model ID to read YAML from.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- gitRef
- targetModelId
properties:
gitRef:
type: string
description: >-
Git reference (branch name, tag, or commit SHA) to read the
source model YAML from.
example: main
targetModelId:
type: string
format: uuid
description: The shared model ID to write the YAML to.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
branchName:
type: string
description: >
**Required if the target model has git enabled.**. Branch
name on the target model. If the branch doesn't exist, it
will be created.
example: migrate-from-prod
commitMessage:
type: string
description: Git commit message.
example: Migrate model from production
example:
gitRef: main
targetModelId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
branchName: migrate-from-prod
commitMessage: Migrate model from production
responses:
'200':
description: Model migrated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the migration completed successfully.
example: true
example:
success: true
'400':
description: >
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`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >
Forbidden
Possible error messages:
- `Forbidden: User does not have access to the source or target
model`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found
Possible error messages:
- `Not Found: Source model not found`
- `Not Found: Target model not found`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- orgApiKey: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````