---
title: "Create Prompt"
method: POST
path: "/{brand_id}/prompts"
---

# Create Prompt

`POST /{brand_id}/prompts`

Creates a new prompt with variants for the specified platforms. Requires the `configure` scope.

**Behavior:**
- Auto-categorizes the journey stage using an LLM if not provided
- Creates variants for each specified platform
- Reactivates an archived prompt if a duplicate exists
- Dispatches collection events to begin tracking

## Path parameters

- `brand_id` integer, required

## Request body

- APIPromptInputModel — Input model for creating a new prompt to track AI visibility.
  - `text` string, required — The prompt text to track across AI platforms
  - `persona_id` integer, nullable — Optional persona ID to associate with this prompt for segmented analysis
  - `stage` string, nullable — The customer journey stage this prompt represents. Must be the name of one of the brand's active stages (custom stage names included); omit to auto-categorize with an LLM against the brand's stage definitions. Default sets: - `Advice` - Seeking recommendations or guidance - `Awareness` - Exploring a topic or problem space - `Evaluation` - Assessing specific options - `Comparison` - Comparing multiple options - `Other` - Doesn't fit other categories
  - `tags` string[] — Custom tags for categorizing and filtering prompts
  - `key_topics` string[] — Key topics to associate with this prompt from the brand's topic list
  - `language` string, nullable — Lowercase ISO 639-1 code of the language the prompt text is written in (e.g. `pt`). If omitted, the language is detected from the text, falling back to the brand's default language.
  - `platforms` string[] — AI platforms to track this prompt on. If empty, defaults to all supported platforms. **Supported platforms:** - `chatgpt` - OpenAI ChatGPT - `claude` - Anthropic Claude - `google_ai_overviews` - Google AI Overviews (Search) - `perplexity` - Perplexity AI - `meta` - Meta AI - `google_ai_mode` - Google AI Mode - `google_gemini` - Google Gemini - `copilot` - Microsoft Copilot

## Response `200`

Successful Response

- PromptListing — Represents a prompt being tracked for AI visibility, including its configuration and metadata.
  - `id` integer, required — Unique identifier for the prompt
  - `text` string, required — The prompt text being tracked
  - `stage` string, required — The customer journey stage this prompt represents — one of the brand's stages (custom stage names included)
  - `persona_id` integer, nullable, required — ID of the associated persona, if any
  - `platforms` string[], required — AI platforms this prompt is tracked on
  - `tags` string[], required — Custom tags assigned to this prompt
  - `topics` string[], required — Auto-detected or assigned topics for this prompt
  - `branded` boolean, required — Whether this prompt explicitly mentions the brand
  - `favorite` boolean, required — Whether this prompt is marked as a favorite
  - `status` 'active' | 'archived', required — Lifecycle status of the prompt (`active` or `archived`)
  - `created_at` string, date-time, required — Timestamp when the prompt was created

## Other responses

- `422` — Validation Error

---

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