AI APIs

These APIs are in beta

The AI APIs are in beta and may have future breaking changes.

The AI APIs allow you to leverage Omni's AI capabilities to enhance your data exploration and analysis.

Generate a query

Transforms a natural language description into a structured Omni query that can be executed using the Query Run API.

POST /api/unstable/ai/generate-query

curl -X POST 'https://myorg.omniapp.co/api/unstable/ai/generate-query' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer <TOKEN>' \
--d '{
  "modelId": "bcf0cffd-ec1b-44d5-945a-a261ebe407fc",
  "currentTopicName": "order_items",
  "prompt": "Show me top 10 products by sales amount"
}'

Parameters

Parameter	Type	Required	Default	Description
modelId	string	Yes ✓	-	The UUID of the model to use for query generation.
currentTopicName	string	Yes ✓	-	The name of the topic to use as context for the query generation.
prompt	string	Yes ✓	-	The natural language description of the query you want to generate (e.g., "Show me monthly sales trends").
branchId	string	No X	null	Optional ID of the model branch to use. If not provided, the main branch will be used.
contextQuery	object	No X	null	Optional query object to provide as context. Useful when refining or building upon an existing query.
structured	boolean	No X	false	When set to true, the API will return a more strictly structured query format.

Response

200 OK

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

{
  "query": {
    "model_job": {
      "model_id": "bcf0cffd-ec1b-44d5-945a-a261ebe407fc",
      "table": "order_items",
      "fields": [
        "products.item_name",
        "order_items.total_sale_price"
      ],
      "calculations": [],
      "filters": {},
      "sorts": [
        {
          "column_name": "order_items.total_sale_price",
          "sort_descending": true,
          "is_column_sort": false,
          "null_sort": "OMNI_DEFAULT"
        }
      ],
      "limit": 10,
      "pivots": [],
      "fill_fields": [],
      "column_totals": {},
      "row_totals": {},
      "column_limit": 50,
      "default_group_by": true,
      "join_via_map": {},
      "join_paths_from_topic_name": "order_items",
      "version": 5,
      "period_over_period_computations": [],
      "query_references": {},
      "metadata": {},
      "custom_summary_types": {}
    }
  }
}

Field	Type	Description
query	object	A structured Omni query object that can be used with the Query Run API

400 Bad Request

{
  "detail": "<errorReason>",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 400
}

Issue	Error detail
Invalid JSON	Bad Request: Invalid JSON
Invalid method	Invalid method

403 Forbidden

{
  "detail": "<errorReason>",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 403
}

Issue	Error detail
Feature not enabled	Feature is not enabled

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": "<errorReason>",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 500
}

Issue	Error detail
AI service error	No response from AI or other AI service-related errors