Create perception prompts

Add perception prompts to a brand.

POST /v1/brands/{brandId}/perception-prompts

Create perception prompts

cURL

curl --request POST \
  --url https://api.example.com/v1/brands/{brandId}/perception-prompts \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompts": [
    {}
  ]
}
'

Perception prompts are questions (e.g. “How trustworthy does this brand appear on a scale from 0–10?”) that are sent to LLMs to score brand attributes. This endpoint requires the Custom Perception Prompts feature to be enabled for your organization.

Perception prompts share the same quota as regular prompts.

Path parameters

brandId · string · required

Brand UUID. Obtain from List brands.

Request body

prompts · PerceptionPromptInput[] · required

Show PerceptionPromptInput

Request

curl -s -X POST \
  -H "x-spotlight-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      {
        "text": "On a scale from 0 to 10, how trustworthy does this brand appear?",
        "propertyId": "Trust",
        "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter"
      },
      {
        "text": "How clear and easy to understand is this brand'"'"'s messaging?",
        "propertyId": "Clarity",
        "goodScore": "Messaging is clear and compelling",
        "badScore": "Messaging is confusing or inconsistent"
      }
    ]
  }' \
  "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception-prompts"

Response

{
  "prompts": [
    {
      "id": "perception-prompt-uuid-1",
      "brandId": "brand-uuid-123",
      "propertyId": "Trust",
      "promptText": "On a scale from 0 to 10, how trustworthy does this brand appear?",
      "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter"
    }
  ],
  "remainingSlots": 85
}

Errors

Status	Code	Description
403	custom_perception_prompts_disabled	Custom perception prompts are not enabled for this organization or brand.
409	prompt_limit_exceeded	Prompt quota reached. See Errors.