Skip to main content
POST
/
v1
/
ai
/
pick-topic
Pick topic
curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/pick-topic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "prompt": "How many orders were placed last month?",
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "currentTopicName": "order_items",
  "potentialTopicNames": [
    "order_items",
    "customers",
    "products"
  ],
  "userId": "990e8400-e29b-41d4-a716-446655440004",
  "queryAllViews": false
}
'
{
  "topicId": "order_items"
}

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.

Authorizations

​
Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Body

application/json
​
modelId
string<uuid>
required

The UUID of the shared model to query against. Note that:

  • Only shared models are supported
  • The user must have Querier permissions or higher on the model
Example:

"770e8400-e29b-41d4-a716-446655440002"

​
prompt
string
required

The natural language prompt to analyze. The AI will determine which topic best matches the data described in this prompt.

Example:

"How many orders were placed last month?"

​
branchId
string<uuid>

Optional branch ID for the model. Must be a branch of the shared model specified by modelId.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
currentTopicName
string

The name of the current topic to scope query generation. If not provided, AI will automatically select the best topic for the prompt.

Example:

"order_items"

​
potentialTopicNames
string[]

Optional list of topic names to limit consideration to. If not provided, all topics the user has access to in the model will be evaluated.

Example:
["order_items", "customers", "products"]
​
userId
string<uuid>

User ID to evaluate topic access as. Their permissions will be used for permission-aware topic selection.

Only valid with Organization API keys. PATs always act as the authenticated user.

Example:

"990e8400-e29b-41d4-a716-446655440004"

​
queryAllViews
boolean
default:false

When true and the model's query_all_views_and_fields setting is enabled, allows the AI to access views that are not included in topics when selecting a topic. If the setting is disabled, this parameter has no effect.

When both the API parameter and model setting are enabled:

  • The AI can select from any view in the model, including views not in topics
  • The AI will prefer topic-organized views unless the question clearly targets a standalone view

Note: Users with topic-locked permissions cannot use this parameter, even if the model setting is enabled.

Response

Topic selected successfully. The returned topicId can be used as the topicName parameter in other AI endpoints.

​
topicId
string
required

The name of the topic that best matches the prompt.

Use this as the topicName parameter when calling the Generate a query or the Create AI job endpoints.

Example:

"order_items"