Topics & Prompts
Create perception prompts
Add perception prompts to a brand.
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": [
{}
]
}
'import requests
url = "https://api.example.com/v1/brands/{brandId}/perception-prompts"
payload = { "prompts": [{}] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({prompts: [{}]})
};
fetch('https://api.example.com/v1/brands/{brandId}/perception-prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/brands/{brandId}/perception-prompts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompts' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/brands/{brandId}/perception-prompts"
payload := strings.NewReader("{\n \"prompts\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/brands/{brandId}/perception-prompts")
.header("Content-Type", "application/json")
.body("{\n \"prompts\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/brands/{brandId}/perception-prompts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompts\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_bodyPerception 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
Brand UUID. Obtain from List brands.
Request body
Show PerceptionPromptInput
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. |
⌘I
Create perception prompts
curl --request POST \
--url https://api.example.com/v1/brands/{brandId}/perception-prompts \
--header 'Content-Type: application/json' \
--data '
{
"prompts": [
{}
]
}
'import requests
url = "https://api.example.com/v1/brands/{brandId}/perception-prompts"
payload = { "prompts": [{}] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({prompts: [{}]})
};
fetch('https://api.example.com/v1/brands/{brandId}/perception-prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/brands/{brandId}/perception-prompts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompts' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/brands/{brandId}/perception-prompts"
payload := strings.NewReader("{\n \"prompts\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/brands/{brandId}/perception-prompts")
.header("Content-Type", "application/json")
.body("{\n \"prompts\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/brands/{brandId}/perception-prompts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompts\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body