Add prompts to a topic cluster
curl --request POST \
--url https://api.snowseo.com/v3/topic-clusters/{topicId}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"teamId": "<string>",
"prompts": [
{
"promptId": "<string>",
"prompt": "<string>",
"intent": "<string>",
"region": {
"type": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"iso2": "<string>",
"iso3": "<string>"
}
}
],
"intents": {},
"track": true
}
'import requests
url = "https://api.snowseo.com/v3/topic-clusters/{topicId}/prompts"
payload = {
"teamId": "<string>",
"prompts": [
{
"promptId": "<string>",
"prompt": "<string>",
"intent": "<string>",
"region": {
"type": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"iso2": "<string>",
"iso3": "<string>"
}
}
],
"intents": {},
"track": True
}
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({
teamId: '<string>',
prompts: [
{
promptId: '<string>',
prompt: '<string>',
intent: '<string>',
region: {
type: '<string>',
city: '<string>',
state: '<string>',
country: '<string>',
iso2: '<string>',
iso3: '<string>'
}
}
],
intents: {},
track: true
})
};
fetch('https://api.snowseo.com/v3/topic-clusters/{topicId}/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.snowseo.com/v3/topic-clusters/{topicId}/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([
'teamId' => '<string>',
'prompts' => [
[
'promptId' => '<string>',
'prompt' => '<string>',
'intent' => '<string>',
'region' => [
'type' => '<string>',
'city' => '<string>',
'state' => '<string>',
'country' => '<string>',
'iso2' => '<string>',
'iso3' => '<string>'
]
]
],
'intents' => [
],
'track' => true
]),
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.snowseo.com/v3/topic-clusters/{topicId}/prompts"
payload := strings.NewReader("{\n \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\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.snowseo.com/v3/topic-clusters/{topicId}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.snowseo.com/v3/topic-clusters/{topicId}/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 \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"linked": 123,
"created": 123,
"promptIds": [
"<string>"
],
"skipped": 123,
"promptsSkipped": 123,
"alreadyLinked": 123
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}Topic Clusters
Topic Prompts
Add AI visibility prompts to a topic cluster.
POST
/
v3
/
topic-clusters
/
{topicId}
/
prompts
Add prompts to a topic cluster
curl --request POST \
--url https://api.snowseo.com/v3/topic-clusters/{topicId}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"teamId": "<string>",
"prompts": [
{
"promptId": "<string>",
"prompt": "<string>",
"intent": "<string>",
"region": {
"type": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"iso2": "<string>",
"iso3": "<string>"
}
}
],
"intents": {},
"track": true
}
'import requests
url = "https://api.snowseo.com/v3/topic-clusters/{topicId}/prompts"
payload = {
"teamId": "<string>",
"prompts": [
{
"promptId": "<string>",
"prompt": "<string>",
"intent": "<string>",
"region": {
"type": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"iso2": "<string>",
"iso3": "<string>"
}
}
],
"intents": {},
"track": True
}
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({
teamId: '<string>',
prompts: [
{
promptId: '<string>',
prompt: '<string>',
intent: '<string>',
region: {
type: '<string>',
city: '<string>',
state: '<string>',
country: '<string>',
iso2: '<string>',
iso3: '<string>'
}
}
],
intents: {},
track: true
})
};
fetch('https://api.snowseo.com/v3/topic-clusters/{topicId}/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.snowseo.com/v3/topic-clusters/{topicId}/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([
'teamId' => '<string>',
'prompts' => [
[
'promptId' => '<string>',
'prompt' => '<string>',
'intent' => '<string>',
'region' => [
'type' => '<string>',
'city' => '<string>',
'state' => '<string>',
'country' => '<string>',
'iso2' => '<string>',
'iso3' => '<string>'
]
]
],
'intents' => [
],
'track' => true
]),
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.snowseo.com/v3/topic-clusters/{topicId}/prompts"
payload := strings.NewReader("{\n \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\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.snowseo.com/v3/topic-clusters/{topicId}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.snowseo.com/v3/topic-clusters/{topicId}/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 \"teamId\": \"<string>\",\n \"prompts\": [\n {\n \"promptId\": \"<string>\",\n \"prompt\": \"<string>\",\n \"intent\": \"<string>\",\n \"region\": {\n \"type\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\",\n \"iso2\": \"<string>\",\n \"iso3\": \"<string>\"\n }\n }\n ],\n \"intents\": {},\n \"track\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"linked": 123,
"created": 123,
"promptIds": [
"<string>"
],
"skipped": 123,
"promptsSkipped": 123,
"alreadyLinked": 123
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}Add AI prompts (questions people ask AI tools) to a topic cluster. Body:
prompts, where each item is { promptId } to link an existing prompt or { prompt, intent?, region? } to create one (max 2000 characters), plus optional intents and track. A prompt already in another topic is skipped. The response is { success, linked, created, skipped, promptsSkipped, alreadyLinked, promptIds }.
Set track: true to have SnowSEO monitor how often your brand appears in AI-generated answers for the prompts it newly links. It enables tracking only; prompts already being tracked are not disabled.
Prompts are only analyzed when
track is true. Analysis runs in the background and uses AI credits per platform for prompts that have never run; prompts your balance can’t cover are left untracked and counted in promptsSkipped. It may take a few minutes before AI visibility data appears.Authorizations
bearerAuthapiKey
Your SnowSEO API key (sk_...).
Path Parameters
Topic cluster ID
Body
application/json
Each item is either { promptId } to link an existing prompt or { prompt, intent, region? } to create a new one. region is the structured country-level object { type, city, state, country, iso2, iso3 }; omit for worldwide.
Show child attributes
Show child attributes
Map of prompt text → intent override
Show child attributes
Show child attributes
Whether to enable tracking on newly linked prompts
Was this page helpful?

