---
title: "Pick topic"
method: POST
path: "/v1/ai/pick-topic"
tags: ["AI"]
---

# Pick topic

`POST /v1/ai/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.

## Request body

- AiPickTopicBody
  - `branchId` string, uuid — Optional branch ID for the model. Must be a branch of the shared model specified by modelId.
  - `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.
  - `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
  - `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.
  - `prompt` string, required — The natural language prompt to analyze. The AI will determine which topic best matches the data described in this prompt.
  - `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.
  - `queryAllViews` boolean — When `true` and the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/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 `200`

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

- AiPickTopicResponse
  - `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](/api/ai/generate-a-query) or the [Create AI job](/api/ai/create-ai-job) endpoints.

## Other responses

- `400` — Invalid request body. The `prompt` or `modelId` may be missing or malformed.
- `401` — Missing or invalid API key.
- `403` — Insufficient permissions. Requires the **Querier** role on the specified model.
- `404` — The specified model was not found, or no accessible topics exist in the model.
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)
- `500` — AI service error.

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)