---
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:**
- `stage` is optional. If omitted, the journey stage is auto-classified against your brand's active stages using an LLM.
- If `stage` is provided, it must match one of your brand's active stages (case-sensitive display name). An unknown value returns `400`. An explicit stage is treated as a manual assertion and won't be overwritten by later re-classification.
- 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 — The unique identifier for the brand

## 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 match one of your brand's active stages (case-sensitive display name); custom stage names are accepted. Omit to auto-classify against the brand's stage definitions. **Default stage sets:** - **Intent (v1)** — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other` - **Funnel (v2)** — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other` Unknown stage names return `400 Bad Request`. An explicit stage is treated as a manual selection and won't be reclassified later.
  - `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`, `ja`, `es`). Case-insensitive; uppercase input is normalized. Invalid codes return `422 Unprocessable Entity`. If omitted, the language is auto-detected from the prompt 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. Returned as the display name of the brand's active stage — one of the brand's default set (`Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other` for intent brands; `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other` for funnel brands) or a custom stage name.
  - `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
  - `created_at` string, date-time, required — Timestamp when the prompt was created

## Other responses

- `422` — Validation Error

---

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