Sign in

v1

latestOpenAPI 3.1.02026-07-263370112.1 KB

Create Prompt

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.
post/{brand_id}/prompts

Path parameters

brand_idinteger required

The unique identifier for the brand

The unique identifier for the brand

Request body

textstring required

The prompt text to track across AI platforms

persona_idinteger nullable

Optional persona ID to associate with this prompt for segmented analysis

stagestring 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.

tagsstring[]

Custom tags for categorizing and filtering prompts

key_topicsstring[]

Key topics to associate with this prompt from the brand's topic list

languagestring 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.

platformsstring[]

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

Successful Response

idinteger required

Unique identifier for the prompt

textstring required

The prompt text being tracked

stagestring 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_idinteger nullable required

ID of the associated persona, if any

platformsstring[] required

AI platforms this prompt is tracked on

tagsstring[] required

Custom tags assigned to this prompt

topicsstring[] required

Auto-detected or assigned topics for this prompt

created_atstring date-time required

Timestamp when the prompt was created