Models APIs

The model APIs allow you to interact with models in Omni.

Create a model

Creates a new model.

POST /api/unstable/models
curl -L -X POST 'https://myorg.omniapp.co/api/unstable/models' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "connectionId": "conn_123",
  "modelKind": "SCHEMA",
  "modelName": "My New Model",
  "accessGrants": [
    {
      "name": "test-grant",
      "accessBoostable": true
    }
  ]
}'

Typical workflow

The typical workflow for using this endpoint is:

Create a schema model using this endpoint
Use the refresh endpoint to load the schema for the created model
Create shared models based on the schema model

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "model": {
    "baseModelId": null,
    "connectionId": "conn_123",
    "createdAt": "2023-01-01T00:00:00Z",
    "deletedAt": null,
    "id": "model-id-1",
    "modelKind": "SCHEMA",
    "name": "My New Model",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
}

Field	Type	Description
model	object	The created model
model.baseModelId	string \| null	ID of the base model (if applicable)
model.connectionId	string \| null	ID of the connection
model.createdAt	string	Creation timestamp
model.deletedAt	string \| null	Deletion timestamp (if deleted)
model.id	string	Model ID
model.modelKind	string \| null	Type of model
model.name	string \| null	Model name
model.updatedAt	string	Last update timestamp

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid request body	`Bad Request: Invalid parameter value`
Schema model already exists	`Bad Request: Schema model already exists for the connection`
Schema model does not exist	`Bad Request: Schema model does not exist when creating a non-schema model`
Branch schema refresh enabled	`Bad Request: Shared model cannot be created when branch schema refresh is enabled`

403 Forbidden

{
  "detail": "Forbidden",
  "status": 403
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

List models

Retrieves a paginated list of models with their metadata.

GET /api/unstable/models
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: All parameters must be provided as query parameters.

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "next_page_cursor",
    "pageSize": 20,
    "totalRecords": 42
  },
  "records": [
    {
      "baseModelId": null,
      "connectionId": "conn_123",
      "createdAt": "2023-01-01T00:00:00Z",
      "deletedAt": null,
      "id": "model-id-1",
      "modelKind": "SCHEMA",
      "name": "My Schema Model",
      "updatedAt": "2023-01-01T00:00:00Z"
    }
  ]
}

Field	Type	Description
pageInfo	object	Pagination information
pageInfo.hasNextPage	boolean	Indicates if there are more records available
pageInfo.nextCursor	string \| null	Cursor for the next page of results
pageInfo.pageSize	number	Number of records per page
pageInfo.totalRecords	number	Total number of records matching the query
records	array	List of model records
records.baseModelId	string \| null	ID of the base model (if applicable)
records.branches	array	List of branch models (only included when `include=activeBranches`)
records.connectionId	string \| null	ID of the connection
records.createdAt	string	Creation timestamp
records.deletedAt	string \| null	Deletion timestamp (if deleted)
records.id	string	Model ID
records.modelKind	string \| null	Type of model
records.name	string \| null	Model name
records.updatedAt	string	Last update timestamp

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid query parameters	`Bad Request: Invalid parameter value`

403 Forbidden

{
  "detail": "Forbidden",
  "status": 403
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Delete a branch model

Deletes a branch associated with the specified shared model.

DELETE /api/unstable/models/:modelId/branch/:branchName
curl -L -X DELETE 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/branch/feature-branch' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: All parameters must be provided as URL parameters.

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true
}

Field	Type	Description
success	boolean	Indicates whether the operation was successful

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid modelId format	`Bad Request: Invalid modelId format`
Method not allowed	`Bad Request: Method not allowed`

403 Forbidden

{
  "detail": "Forbidden",
  "status": 403
}

404 Not Found

{
  "detail": "Shared model or branch model does not exist",
  "status": 404
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Refresh a schema

Refreshes 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. Note: This will remove structures that are no longer present in the source, but not anything created by users.

POST /v0/model/:id/refresh
curl -L -X POST 'https://myorg.omniapp.co/api/v0/model/bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed/refresh' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Name	Type	Required	Description
id	URL parameter	✓	The ID of the model to be refreshed.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
    "modelId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
    "status": "running"
}

Field	Type	Description
modelId	string	ID of the model
status	string	Status of the schema refresh. This value will be `running` to indicate that the refresh has started.

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid model ID	`Bad Request: modelId: Invalid uuid`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Reset a cache policy

note

Reach out to Omni support to enable the cache policy reset API.

Resets the cache for the specified cache policy.

Basic request
With reset date

POST /api/unstable/model/:modelId/cache_reset/:cachePolicyName
curl -L 'https://myorg.omniapp.co/api/unstable/model/bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed/cache_reset/daily_cache_policy' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer <TOKEN>'

POST /api/unstable/model/:modelId/cache_reset/:cachePolicyName
curl -L 'https://myorg.omniapp.co/api/unstable/model/bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed/cache_reset/daily_cache_policy' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer <TOKEN>' \
--d '{
    "resetAt": "2025-01-30T22:30:52.872Z"
}'

Parameters

Parameter	Type	Required	Default	Description
modelId	URL parameter	Yes ✓	-	The ID of the model.
cachePolicyName	URL parameter	Yes ✓	-	The name of the cache policy to reset.
resetAt	string (date)	No X	Now	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. Defaults to now. Cannot be a future date.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
    "success": true,
    "cache_reset": {
        "id": "98e14685-597b-4887-a50f-34e93985e00d",
        "model_id": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
        "policy_name": "daily_cache_policy",
        "created_at": 1742851818.561,
        "updated_at": 1742932587.717,
        "reset_at": 1738276252.872
    }
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid model ID	`Bad Request: modelId: Invalid uuid`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Retrieve model YAML specification

Retrieves the YAML representation of a model with optional filtering and mode selection.

Basic request
With branch ID
Filter by file name
Filter by regex pattern
Extension mode

GET /api/unstable/models/:modelId/yaml
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/yaml' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

GET /api/unstable/models/:modelId/yaml?branchId=<branchId>
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/yaml?branchId=987fcdeb-a89b-12d3-a456-426614174000' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

GET /api/unstable/models/:modelId/yaml?fileName=<fileName>
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/yaml?fileName=customers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

GET /api/unstable/models/:modelId/yaml?fileName=<regexPattern>
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/yaml?fileName=^views/.*\\.yaml$' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

GET /api/unstable/models/:modelId/yaml?mode=extension
curl -L -X GET 'https://myorg.omniapp.co/api/unstable/models/123e4567-e89b-12d3-a456-426614174000/yaml?mode=extension' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "files": {
    "model.yaml": "name: Test Model\ntype: model",
    "views/customers.yaml": "name: Customers\nfields: []",
    "views/orders.yaml": "name: Orders\nfields: []"
  },
  "version": 1,
  "viewNames": {}
}

Field	Type	Description
files	object	Map of file paths to YAML content
version	number	Version of the YAML
viewNames	object	Map of view names to their definitions

400 Bad Request

{
  "detail": "Schema models do not have branches"
}

{
  "detail": "Branches are not valid for workbook models with mode=extension, staged"
}

Issue	Error detail
Schema model with branch	`Schema models do not have branches`
Invalid mode with branch	`Branches are not valid for mode=extension, staged`

403 Forbidden

{
  "detail": "Permission denied"
}

{
  "detail": "Feature not enabled"
}

Issue	Error detail
Insufficient permissions	`Permission denied`
Feature not enabled	`Feature not enabled`

404 Not Found

{
  "detail": "Model with id {modelId} does not exist"
}

{
  "detail": "Branch does not exist"
}

Issue	Error detail
Model not found	`Model with id {modelId} does not exist`
Branch not found	`Branch does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

500 Internal Server Error

{
  "detail": "Failed to get model YAML"
}

Create a model​

Typical workflow​

Parameters​

Response​

List models​

Parameters​

Response​

Delete a branch model​

Parameters​

Response​

Refresh a schema​

Parameters​

Response​

Reset a cache policy​

Parameters​

Response​

Retrieve model YAML specification​

Parameters​

Response​

Create a model

Typical workflow

Parameters

Response

List models

Parameters

Response

Delete a branch model

Parameters

Response

Refresh a schema

Parameters

Response

Reset a cache policy

Parameters

Response

Retrieve model YAML specification

Parameters

Response