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

Documentation Index

Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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

StatusCodeDescription
403custom_perception_prompts_disabledCustom perception prompts are not enabled for this organization or brand.
409prompt_limit_exceededPrompt quota reached. See Errors.