Skip to main content

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.

The Create or update YAML files endpoint writes one file per request. When you target a git-enabled shared model directly, each write triggers its own git sync. At hundreds or thousands of files, that results in a process that could take hours. The fix is to write against a model branch instead, then merge the branch once when all updates are complete. Git syncs a single time, on the merge.

Requirements

To follow the steps in this guide, you’ll need:
  • An Omni API key
  • Modeler or higher permissions on the shared model you want to update
  • The shared model’s modelId and connectionId, which you can retrieve using the List models endpoint
1

Create a branch off the shared model

Call the Create model endpoint with modelKind: "BRANCH". Set baseModelId to the shared model you want to branch from and reuse its connectionId.
curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelKind": "BRANCH",
    "baseModelId": "<SHARED_MODEL_ID>",
    "connectionId": "<CONNECTION_ID>",
    "modelName": "<MODEL_NAME>"
  }'
Save two values from the response:
  • id — The branch’s UUID, which you’ll pass as branchId in the next step.
  • modelName — What you provided in the request body. The merge endpoint identifies the branch by name, not by ID, so you need this exact string later.
2

Write YAML files against the branch

For each file, call the Create or update YAML files endpoint:
curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/yaml \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "<BRANCH_ID>",
    "fileName": "<view_name>.view",
    "yaml": "<file contents as a string>",
    "mode": "combined"
  }'
In the path, put the shared model’s ID. For the request body:
  • branchId - The branch UUID from step 1’s response (id). This routes the write operation to the branch instead of the shared model and is required for models where pull requests are required.
  • fileName - The name of the file being created or updated. This can be model, relationships, <topic_name>.topic for topics, or <view_name>.view for view files.
  • yaml - The YAML content of the file as a formatted JSON string
  • mode - Set to combined
  • commitMessage - Required if the model has git enabled. A short commit message for the change.
Loop this call for every file in your batch. Because writes go to the branch, none of them triggers a git sync.If a single write fails partway through, the branch keeps the writes that already succeeded. Fix the failing file and retry just that request before moving on to the merge.
3

Validate before merging

Validation is optional but strongly recommended — it catches issues on the branch before they reach the shared model, where they could break existing dashboards and queries.Two endpoints validate different surfaces: Validate model for the YAML itself, and Validate content for the dashboards and queries that depend on it. Run both for the safest merge.
  • Validate the model. Use the Validate model endpoint to catch broken references, invalid types, and structural issues introduced by your YAML writes. 
    curl -X GET "https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/validate?branchId=<BRANCH_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
  • Validate content. Use the Validate content endpoint to catch dashboards and queries that reference fields or views the branch renamed or removed. Note the query parameter is branch_id (snake_case) on this endpoint. 
    curl -X GET "https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/content-validator?branch_id=<BRANCH_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
Resolve any issues these endpoints return by writing additional YAML updates against the same branch, then re-run validation. Only proceed to the merge once both come back clean.
4

Merge the branch

The Merge branch endpoint can’t be used with models that require pull requests or those using git follower mode. See the Merge branch documentation for more information.
Once every file has been written and validated, merge the branch into the shared model. Use the modelName you saved from the step 1 response as the <BRANCH_MODEL_NAME> in the path:
curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/branch/<BRANCH_MODEL_NAME>/merge \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_branch": true,
    "commit_message": "Bulk YAML import via API"
  }'
Set delete_branch: true to clean up the branch after the merge succeeds.A successful response returns success: true and for git-enabled models, git_synced: true. This is the one git sync for the entire batch of updates.

Next steps