OpenAPI Specification
openapi: 3.1.0
info:
title: Omni AI Models API
description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. \n"
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: Models
description: Create and manage data models
paths:
/v1/models:
post:
tags:
- Models
summary: Create model
description: 'Create a new model. The typical workflow for using this endpoint is:
1. Create a schema model using this endpoint
2. Use the [Refresh schema](/api/models/refresh-schema) endpoint to load the schema for the created model
3. Create shared models based on the schema model
'
security:
- bearerAuth: []
operationId: createModel
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- connectionId
properties:
connectionId:
type: string
format: uuid
description: ID of the connection the model is based on.
modelKind:
type: string
enum:
- SCHEMA
- SHARED
- SHARED_EXTENSION
- BRANCH
default: SCHEMA
description: 'Type of model.
- `SCHEMA` - Mirrors the database structure
- `SHARED` - Represents the universal, governed data model that workbooks are based on
- `SHARED_EXTENSION` - Represents an extension to the `SHARED` model. Can be used to dynamically extend the `SHARED` model based on user attributes, or as a model that workbooks are based on in a departmental use case.
- `BRANCH` - A model layer that is used to develop modifications to the production shared model
For more information, see the [Modeling documentation](/modeling).
'
modelName:
type: string
description: Name of the model.
baseModelId:
type: string
description: '**Applicable to branch and extension models.** ID of the base model.
'
accessGrants:
type: array
default: []
description: List of [access grants](/modeling/develop/data-access-control) for the model.
items:
type: object
properties:
name:
type: string
description: Name of the access grant.
accessBoostable:
type: boolean
description: If `true`, the access grant can be boosted.
allowAsWorkbookBase:
type: boolean
default: false
description: '**Only applicable to `SHARED_EXTENSION` models**. If `true`, allows the model to be selected as a base model when creating workbooks.
'
useIsolatedBranches:
type: boolean
default: false
description: '**Only applicable to `SHARED_EXTENSION` models**. If `true`, branches are shown on the extension model page instead of parent shared model.
'
responses:
'200':
description: Model created successfully
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Error message if creation failed
message:
type: string
description: Additional message
model:
type: object
description: Details about the model
properties:
id:
type: string
format: uuid
description: ID of the created model.
modelKind:
type: string
description: The type of model.
name:
type: string
description: The name of the model.
success:
type: boolean
description: Indicates if the operation succeeded
'400':
description: 'Bad Request
Possible error messages:
- `Bad Request: Invalid parameter value`
- `Bad Request: Schema model already exists for the connection`
- `Bad Request: Schema model does not exist when creating a non-schema model`
- `Bad Request: Shared model cannot be created when branch schema refresh is enabled`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden
Possible error messages:
- `Forbidden`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
get:
tags:
- Models
summary: List models
description: Retrieves a paginated list of models with their metadata.
security:
- bearerAuth: []
operationId: listModels
parameters:
- name: baseModelId
in: query
required: false
schema:
type: string
description: 'Filter models by base model ID.
'
- name: connectionId
in: query
required: false
schema:
type: string
description: 'Filter models by connection ID.
'
- name: includeDeleted
in: query
required: false
schema:
type: boolean
description: 'If `true`, include deleted models.
'
- name: modelId
in: query
required: false
schema:
type: string
description: 'Filter models by a specific model ID.
'
- name: modelKind
in: query
required: false
schema:
type: string
enum:
- SCHEMA
- SHARED
- SHARED_EXTENSION
- WORKBOOK
- BRANCH
- QUERY
- TOPIC
- FIELD_PICKER_TOPIC
description: 'Filter by model kind.
'
- name: name
in: query
required: false
schema:
type: string
description: 'Filter models by name.
'
- name: pageSize
in: query
schema:
type: integer
default: 20
description: Specifies the number of records per page.
- name: cursor
in: query
schema:
type: string
description: Pagination cursor
- name: sortDirection
in: query
required: false
schema:
type: string
default: desc
enum:
- asc
- desc
description: 'Sort direction.
'
- name: sortField
in: query
required: false
schema:
type: string
default: updatedAt
enum:
- name
- modelKind
- connectionId
- baseModelId
- createdAt
- updatedAt
description: "Field to sort by. \n"
- name: include
in: query
schema:
type: string
enum:
- activeBranches
description: 'Comma-separated list of additional fields to include in the response.
- `activeBranches` - Include active branches for each model
'
responses:
'200':
description: Paginated model list
content:
application/json:
schema:
type: object
properties:
pageInfo:
$ref: '#/components/schemas/PageInfo'
records:
type: array
description: List of model records.
items:
allOf:
- $ref: '#/components/schemas/Model'
- type: object
properties:
branches:
type: array
description: List of branch models. Only included when `include=activeBranches`.
items:
$ref: '#/components/schemas/Model'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}:
patch:
tags:
- Models
summary: Rename model
description: "<Warning>\n Workbook models and query models cannot be renamed via this endpoint.\n</Warning>\n\nRenames a model by updating its name. This endpoint allows you to programmatically rename models without using the UI, which is particularly useful for bulk operations on shared extension models created via `POST /api/v1/models`.\n\nThe new name must be unique among active models with the same `modelKind` and `baseModelId`.\n\n**Branch-specific constraints:**\n\n- Name must match git-compatible regex: `[\\w\\-/]+`\n- No git ref path conflicts (e.g., cannot rename to `team` if `team/project` exists)\n- Cannot rename branches with an open pull request (when `pullRequestUrl` is set) — renaming would desync Omni from the git remote\n"
security:
- bearerAuth: []
operationId: renameModel
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: ID of the model to rename.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The new name for the model.
example: customer_metrics_v2
responses:
'200':
description: Model renamed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: 'Bad Request
Possible error messages:
- `Bad Request: Cannot rename models of kind WORKBOOK`
- `Bad Request: Cannot rename models of kind QUERY`
- `Bad Request: Model name must be unique`
- `Bad Request: Branch name must match git-compatible regex [\w\-/]+`
- `Bad Request: Branch name would create git ref path conflict`
- `Bad Request: Cannot rename branch with open pull request`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not Found
Possible error messages:
- `Model not found`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/ai-agent-actions:
get:
tags:
- Models
summary: Get model AI agent actions
description: 'Return AI agent actions configured for a model — a unified list of sample queries and skills suitable for surfacing as suggested prompts in AI interfaces.
Sample queries come from both `model.sample_queries` and each topic''s `sample_queries`. Skills come from `model.skills` and each topic''s `skills`, deduped by ID with topic skills overriding model skills.
When no actions are configured at the model or topic level, `records` returns an empty array.
'
security:
- bearerAuth: []
operationId: getModelAiAgentActions
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the model.
responses:
'200':
description: AI agent actions retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates the request was successful
records:
type: array
description: List of AI agent actions (sample queries and skills) configured for the model.
items:
type: object
required:
- type
- id
- label
- description
- prompt
properties:
type:
type: string
enum:
- sample_query
- skill
description: The type of action.
id:
type: string
description: Unique identifier for the action.
label:
type: string
description: Display label for the action.
description:
type: string
description: Description of what the action does.
prompt:
type: string
description: The prompt text to submit to the [Create AI job endpoint](/api/ai/create-ai-job). For skills, this is pre-formatted with the skill envelope.
example:
success: true
records:
- type: sample_query
id: revenue_by_region
label: Revenue by region
description: Show total revenue grouped by region
prompt: Show me revenue by region
- type: skill
id: analyze_trends
label: Analyze trends
description: Analyze trends in the data
prompt: 'Skill: analyze_trends
Analyze trends in revenue over time'
'400':
description: 'Bad Request
Possible error messages:
- `modelId: Invalid UUID`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden
Possible error messages:
- `Permission denied`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found
Possible error messages:
- `Model with id <modelId> does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/branch/{branchName}:
delete:
tags:
- Models
summary: Delete branch
description: Deletes a branch associated with the specified shared model.
security:
- bearerAuth: []
operationId: deleteModelBranch
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: ID of the shared model.
- name: branchName
in: path
required: true
schema:
type: string
description: Name of the branch to delete.
responses:
'200':
description: Branch deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: 'Bad Request
Possible error messages:
- `Bad Request: Invalid modelId format`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not Found
Possible error messages:
- `Shared model or branch model does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/refresh:
post:
tags:
- Models
summary: Refresh schema
description: "<Note>\n This endpoint requires either **Connection Admin** or **Modeler** permissions:\n\n - **Modelers** can use this endpoint on connections that have exactly **one** shared model\n - **Connection Admins** can use this endpoint on any connection they are an admin of, whether the connection has one or multiple models\n</Note>\n\nRefreshes the schema of the specified model. This will cause the model to reflect the latest changes to schemas, views, and fields from the data source. Schema refreshes will remove structures that are no longer present in the source, but not anything created by users.\n\nDepending on whether the **Branch-based schema refresh** setting is configured:\n\n- If **Branch-based schema refresh** is enabled, the `branch_id` query parameter is required. The `branch_id` is validated against the shared model.\n- If **Branch-based schema refresh** isn't enabled, do not provide the `branch_id` parameter. The API will return a `400` error in this case.\n"
security:
- bearerAuth: []
operationId: refreshSchema
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the model to be refreshed.
- name: branch_id
in: query
required: false
schema:
type: string
format: uuid
description: '**Required if Branch-based schema refresh is enabled**. The ID of the branch for models with this setting enabled.
Do not provide this parameter when the setting is not enabled.
'
- name: hard_refresh
in: query
required: false
schema:
type: boolean
default: true
description: 'Whether to perform a hard refresh (removes dropped objects) or soft refresh (additive only). Defaults to true (hard refresh).
'
- name: schemas
in: query
required: false
schema:
type: string
description: 'Comma-separated list of schemas to selectively refresh. Can only be used when `hard_refresh=false`.
'
- name: tables
in: query
required: false
schema:
type: string
description: 'Comma-separated list of tables to selectively refresh. Can only be used when `hard_refresh=false`.
'
responses:
'200':
description: Model refresh started
content:
application/json:
schema:
type: object
properties:
jobId:
type: string
format: uuid
description: ID of the job.
modelId:
type: string
format: uuid
description: ID of the model.
status:
type: string
example: running
description: Status of the schema refresh. This value will be `running` to indicate that the refresh has started.
'400':
description: 'Bad Request
Possible error messages:
- `Bad Request: modelId: Invalid uuid`
- `Bad Request: branch_id: Invalid uuid`
- `Bad Request: branch_id is required when branch schema refresh is enabled`
- `Bad Request: branch_id must not be provided when branch schema refresh is not enabled`
- `Bad Request: selective schemas/tables filters require hard_refresh=false`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not Found
Possible causes:
- Model not found
- Branch not found or does not belong to the model''s shared model
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/cache_reset/{cachePolicyName}:
post:
tags:
- Models
summary: Reset cache
description: "Resets the cache for the specified cache policy.\n\n<Note>\n `cachePolicyName` values are not validated against existing policies. Verify that the values you provide are exact matches to policies in the model.\n</Note>\n"
security:
- bearerAuth: []
operationId: resetModelCache
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the model associated with the cache policy.
- name: cachePolicyName
in: path
required: true
schema:
type: string
description: The name of the cache policy to reset.
requestBody:
content:
application/json:
schema:
type: object
properties:
resetAt:
type: string
format: date-time
description: 'An ISO-8601 date string that sets the time the cache should be reset (invalidated). When set, cache entries created between this value and the current time will still be considered valid. Cannot be a future date. Defaults to now.
'
responses:
'200':
description: Cache reset successfully
content:
application/json:
schema:
type: object
properties:
cache_reset:
type: object
description: The cache reset details.
properties:
id:
type: string
format: uuid
description: ID of the cache reset record.
model_id:
type: string
format: uuid
description: ID of the model.
policy_name:
type: string
description: Name of the cache policy.
created_at:
type: string
format: date-time
description: Timestamp when the cache reset record was created.
updated_at:
type: string
format: date-time
description: Timestamp when the cache reset record was last updated.
reset_at:
type: string
format: date-time
description: Timestamp when the cache was reset.
success:
type: boolean
description: Indicates the request was successful.
'400':
description: 'Bad Request
Possible error messages:
- `Model with id <modelId> does not exist`
- `resetAt cannot be future dated`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found
Possible error messages:
- `Model with id <modelId> does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/yaml:
post:
tags:
- Models
summary: Create or update YAML files
description: 'Creates or overwrites a YAML file for a model. The file can be a special file (`model` or `relationships`) or a YAML file ending in `.topic` or `.view`.
The following models cannot be edited using this endpoint:
- Schema models
- Models using git follower mode
'
security:
- bearerAuth: []
operationId: updateModelYaml
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the model.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- fileName
- yaml
- mode
properties:
branchId:
type: string
format: uuid
description: '**Required if git pull requests are required for the model.** The ID of the branch to create or update. To retrieve branch IDs, use the [List models](/api/models/list-models) endpoint with `modelKind=BRANCH`.
'
fileName:
type: string
description: 'The name of the YAML file. Valid values are:
- `model` - [Model file](/modeling/models)
- `relationships` - [Relationships file](/modeling/relationships)
- `<topic_name>.topic` - [Topic file](/modeling/topics/parameters)
- `<view_name>.view` - [View file](/modeling/views)
'
yaml:
type: string
description: 'The YAML contents of the file. This can be empty, in which case:
- If empty and used with `mode: extension` the file will be removed from the model
- If empty and used with `mode: combined`, the file will be ignored in the model
'
mode:
type: string
default: combined
enum:
- combined
- extension
- staged
- merged
- history
description: 'The mode to use when creating or overwriting the YAML file.
**Note**: Workbook models must use `combined` mode if there is a `branchId`.
'
commitMessage:
type: string
description: '**Required for [git-enabled models](/integrations/git).** Commit message describing the change.
'
previousChecksum:
type: string
description: 'Checksum of the file when fetched, for conflict detection. Obtain this value from the [Get model YAML endpoint](/api/models/get-model-yaml) by including the `includeChecksums` parameter.
If the file has been modified since you fetched it, the request will fail with a `File has been modified since it was fetched` error.
'
fullyResolved:
type: boolean
default: false
description: 'If `true`, accepts fully-resolved YAML. This means that Omni will resolve any extension (`extends`) usage and place the changes into the appropriate model files.
When `false` (default), the YAML is saved as-is to the specified file. This means that even if extensions are used, they will not be included in the changes.
'
responses:
'200':
description: YAML file updated successfully
content:
application/json:
schema:
type: object
properties:
fileName:
type: string
description: The name of the file that was created or updated.
success:
type: boolean
description: Indicates the request was successful.
'400':
description: 'Bad Request
Possible error messages:
- `<parameter>: <parameter> is required`
- `modelId: Invalid uuid`
- `branchId: Invalid uuid`
- `<parameter>: Invalid value <description>`
- `File has been modified since it was fetched`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden
Possible error messages:
- `Permission denied`
- `Feature not enabled`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found
Possible error messages:
- `Model with id <modelId> does not exist`
- `Branch does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
get:
tags:
- Models
summary: Get model YAML
description: Retrieves the YAML representation of a model with optional filtering and mode selection.
security:
- bearerAuth: []
operationId: getModelYaml
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the model.
- name: branchId
in: query
schema:
type: string
format: uuid
description: The ID of the branch to retrieve YAML from. Only valid for shared models in `combined` mode. To retrieve branch IDs, use the [List models](/api/models/list-models) endpoint with `modelKind=BRANCH`.
- name: fileName
in: query
schema:
type: string
description: Filter YAML files by name. Can be a string or a regex pattern.
- name: mode
in: query
schema:
type: string
default: combined
enum:
- extension
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omni/refs/heads/main/openapi/omni-models-api-openapi.yml