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

# Create perception prompts

> Add perception prompts to a brand.

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

<ParamField path="brandId" type="string" required>
  Brand UUID. Obtain from [List brands](/api-reference/brands/list).
</ParamField>

### Request body

<ParamField body="prompts" type="PerceptionPromptInput[]" required>
  <Expandable title="PerceptionPromptInput" />
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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](/errors).                              |