---
title: "Pick the best topic for a prompt"
method: POST
path: "/api/v1/ai/pick-topic"
tags: ["AI"]
---

# Pick the best topic for a prompt

`POST /api/v1/ai/pick-topic`

Analyze a natural language prompt and determine which topic in the model is the best fit for answering the question. Useful as a preprocessing step before calling generate-query or submitting an AI job, 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 your prompt.
  - `modelId` string, uuid, required — The UUID of the shared model to query against. Only shared models are supported.
  - `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-scoped API keys. Personal access tokens always act as the authenticated user.

## 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 generate-query or submitting an AI job.

## 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 target model and AI must be enabled for the organization.
- `404` — The specified model was not found, or no accessible topics exist in the model.
- `500` — AI service error.

---

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