curl --request POST \
--url https://api.scrunchai.com/v1/{brand_id}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "<string>",
"persona_id": 123,
"stage": "<string>",
"tags": [],
"key_topics": [],
"language": "<string>",
"platforms": []
}
'import requests
url = "https://api.scrunchai.com/v1/{brand_id}/prompts"
payload = {
"text": "<string>",
"persona_id": 123,
"stage": "<string>",
"tags": [],
"key_topics": [],
"language": "<string>",
"platforms": []
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: '<string>',
persona_id: 123,
stage: '<string>',
tags: [],
key_topics: [],
language: '<string>',
platforms: []
})
};
fetch('https://api.scrunchai.com/v1/{brand_id}/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.scrunchai.com/v1/{brand_id}/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([
'text' => '<string>',
'persona_id' => 123,
'stage' => '<string>',
'tags' => [
],
'key_topics' => [
],
'language' => '<string>',
'platforms' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.scrunchai.com/v1/{brand_id}/prompts"
payload := strings.NewReader("{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.scrunchai.com/v1/{brand_id}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrunchai.com/v1/{brand_id}/prompts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"text": "<string>",
"stage": "<string>",
"persona_id": 123,
"platforms": [
"chatgpt"
],
"tags": [
"<string>"
],
"topics": [
"<string>"
],
"status": "active",
"created_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Create Prompt
Creates a new prompt with variants for the specified platforms. Requires the configure scope.
Behavior:
stageis optional. If omitted, the journey stage is auto-classified against your brand’s active stages using an LLM.- If
stageis provided, it must match one of your brand’s active stages (case-sensitive display name). An unknown value returns400. 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
400withtype=paused_duplicateand the pausedprompt_id. - Dispatches collection events to begin tracking.
curl --request POST \
--url https://api.scrunchai.com/v1/{brand_id}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "<string>",
"persona_id": 123,
"stage": "<string>",
"tags": [],
"key_topics": [],
"language": "<string>",
"platforms": []
}
'import requests
url = "https://api.scrunchai.com/v1/{brand_id}/prompts"
payload = {
"text": "<string>",
"persona_id": 123,
"stage": "<string>",
"tags": [],
"key_topics": [],
"language": "<string>",
"platforms": []
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: '<string>',
persona_id: 123,
stage: '<string>',
tags: [],
key_topics: [],
language: '<string>',
platforms: []
})
};
fetch('https://api.scrunchai.com/v1/{brand_id}/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.scrunchai.com/v1/{brand_id}/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([
'text' => '<string>',
'persona_id' => 123,
'stage' => '<string>',
'tags' => [
],
'key_topics' => [
],
'language' => '<string>',
'platforms' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.scrunchai.com/v1/{brand_id}/prompts"
payload := strings.NewReader("{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.scrunchai.com/v1/{brand_id}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrunchai.com/v1/{brand_id}/prompts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"<string>\",\n \"persona_id\": 123,\n \"stage\": \"<string>\",\n \"tags\": [],\n \"key_topics\": [],\n \"language\": \"<string>\",\n \"platforms\": []\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"text": "<string>",
"stage": "<string>",
"persona_id": 123,
"platforms": [
"chatgpt"
],
"tags": [
"<string>"
],
"topics": [
"<string>"
],
"status": "active",
"created_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier for the brand
Body
Input model for creating a new prompt to track AI visibility.
The prompt text to track across AI platforms
Optional persona ID to associate with this prompt for segmented analysis
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.
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 topics to associate with this prompt from the brand's topic list
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.
AI platforms to track this prompt on. If empty, defaults to all supported platforms.
Supported platforms:
chatgpt- OpenAI ChatGPTclaude- Anthropic Claudegoogle_ai_overviews- Google AI Overviews (Search)perplexity- Perplexity AImeta- Meta AIgoogle_ai_mode- Google AI Modegoogle_gemini- Google Geminicopilot- Microsoft Copilot
chatgpt, claude, google_ai_overviews, perplexity, meta, google_ai_mode, google_gemini, copilot, grok Response
Successful Response
Represents a prompt being tracked for AI visibility, including its configuration and metadata.
Unique identifier for the prompt
The prompt text being tracked
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.
ID of the associated persona, if any
AI platforms this prompt is tracked on
chatgpt, claude, google_ai_overviews, perplexity, meta, google_ai_mode, google_gemini, copilot, grok Custom tags assigned to this prompt
Auto-detected or assigned topics for this prompt
Lifecycle status of the prompt (active, paused, or archived)
active, paused, archived Timestamp when the prompt was created