> ## 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. # Pick topic > Analyze a natural language prompt and determines which topic in the model is the best fit for answering the question. Useful as a preprocessing step before calling the [Generate AI query](/api/ai/generate-a-query) or [Create AI job](/api/ai/create-ai-job) endpoints, especially when the user's question could relate to multiple topics. ## OpenAPI ````yaml /api/openapi.yaml post /v1/ai/pick-topic openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. 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: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/ai/pick-topic: post: tags: - AI summary: Pick topic description: > Analyze a natural language prompt and determines which topic in the model is the best fit for answering the question. Useful as a preprocessing step before calling the [Generate AI query](/api/ai/generate-a-query) or [Create AI job](/api/ai/create-ai-job) endpoints, especially when the user's question could relate to multiple topics. operationId: aiPickTopic requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AiPickTopicBody' responses: '200': description: >- Topic selected successfully. The returned `topicId` can be used as the `topicName` parameter in other AI endpoints. content: application/json: schema: $ref: '#/components/schemas/AiPickTopicResponse' '400': description: >- Invalid request body. The `prompt` or `modelId` may be missing or malformed. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Insufficient permissions. Requires the **Querier** role on the specified model. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The specified model was not found, or no accessible topics exist in the model. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' '500': description: AI service error. security: - bearerAuth: [] components: schemas: AiPickTopicBody: type: object required: - prompt - modelId properties: branchId: type: string format: uuid description: >- Optional branch ID for the model. Must be a branch of the shared model specified by modelId. example: 550e8400-e29b-41d4-a716-446655440000 currentTopicName: type: string description: >- 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 modelId: type: string format: uuid description: | 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 potentialTopicNames: type: array items: type: string description: >- 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 prompt: type: string description: >- 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? userId: type: string format: uuid description: > 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: type: boolean default: false description: > When `true` and the model's [`query_all_views_and_fields`](/modeling/models/ai-settings#param-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. AiPickTopicResponse: type: object required: - topicId properties: topicId: type: string description: > The name of the topic that best matches the prompt. Use this as the `topicName` parameter when calling the [Generate a query](/api/ai/generate-a-query) or the [Create AI job](/api/ai/create-ai-job) endpoints. example: order_items Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````