SCscrunch

Create Prompt

Changed on

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. A duplicate of a paused prompt is not reactivated; it returns 400 with type=paused_duplicate and the paused prompt_id.
  • Dispatches collection events to begin tracking.
post/{brand_id}/prompts

Request

Path parameters

brand_idinteger required

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. Each tag name is limited to 64 characters; a longer name returns 400 Bad Request with code tag_name_too_long. Separate multiple tags with commas instead of joining them into one name.

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

status'active' | 'paused' | 'archived' required

Lifecycle status of the prompt (active, paused, or archived)

created_atstring date-time required

Timestamp when the prompt was created

Changes

  • e37811b6bc07Revision changes
    • info

      added the non-success response with the status

    • info

      added the required property to the response with the status