curl --request POST \
--url https://app.surfacd.com/api/v1/projects/{project}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompts": [
{
"text": "<string>",
"country_code": "<string>",
"topic": "<string>",
"tags": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
]
}
'import requests
url = "https://app.surfacd.com/api/v1/projects/{project}/prompts"
payload = { "prompts": [
{
"text": "<string>",
"country_code": "<string>",
"topic": "<string>",
"tags": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
] }
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({
prompts: [
{
text: '<string>',
country_code: '<string>',
topic: '<string>',
tags: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
}
]
})
};
fetch('https://app.surfacd.com/api/v1/projects/{project}/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://app.surfacd.com/api/v1/projects/{project}/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' => [
[
'text' => '<string>',
'country_code' => '<string>',
'topic' => '<string>',
'tags' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
]
]
]
]),
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://app.surfacd.com/api/v1/projects/{project}/prompts"
payload := strings.NewReader("{\n \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\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://app.surfacd.com/api/v1/projects/{project}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.surfacd.com/api/v1/projects/{project}/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 \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"created": 123,
"skipped": 123,
"updated": 123,
"activated": 123,
"prompts": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"keyword": "<string>",
"search_volume": 123,
"topic": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"country": {
"code": "<string>",
"name": "<string>"
},
"tags": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"color": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
]
}{
"message": "<string>"
}{
"message": "<string>",
"errors": {}
}Create Prompts
Creates one or more prompts on a project.
Side effects — this is not a passive write:
- Adding new active prompts normally starts a data collection run, which consumes credits. Exception: projects on a manual schedule do not auto-run after their first run — for those you must request a run separately.
- A keyword and search volume are generated automatically for each new prompt by the pipeline; you cannot supply them.
Duplicates of existing prompts (same text + country) are not re-created: an inactive duplicate is reactivated, and tag/topic changes are merged onto the existing prompt. New prompts are created with status active. Requests are rejected when they would exceed the project’s prompt limit or the team’s available credits.
curl --request POST \
--url https://app.surfacd.com/api/v1/projects/{project}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompts": [
{
"text": "<string>",
"country_code": "<string>",
"topic": "<string>",
"tags": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
]
}
'import requests
url = "https://app.surfacd.com/api/v1/projects/{project}/prompts"
payload = { "prompts": [
{
"text": "<string>",
"country_code": "<string>",
"topic": "<string>",
"tags": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
] }
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({
prompts: [
{
text: '<string>',
country_code: '<string>',
topic: '<string>',
tags: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
}
]
})
};
fetch('https://app.surfacd.com/api/v1/projects/{project}/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://app.surfacd.com/api/v1/projects/{project}/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' => [
[
'text' => '<string>',
'country_code' => '<string>',
'topic' => '<string>',
'tags' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
]
]
]
]),
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://app.surfacd.com/api/v1/projects/{project}/prompts"
payload := strings.NewReader("{\n \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\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://app.surfacd.com/api/v1/projects/{project}/prompts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.surfacd.com/api/v1/projects/{project}/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 \"prompts\": [\n {\n \"text\": \"<string>\",\n \"country_code\": \"<string>\",\n \"topic\": \"<string>\",\n \"tags\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"created": 123,
"skipped": 123,
"updated": 123,
"activated": 123,
"prompts": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"keyword": "<string>",
"search_volume": 123,
"topic": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"country": {
"code": "<string>",
"name": "<string>"
},
"tags": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"color": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
]
}{
"message": "<string>"
}{
"message": "<string>",
"errors": {}
}Authorizations
Team API key created in Team Settings. Use it with URLs for the same team.
Path Parameters
Project UUID.
Body
1 - 200 elementsShow child attributes
Show child attributes
Response
Result summary with the newly created prompts.
Number of new prompts created.
Number of duplicates skipped with no change.
Number of existing prompts whose tags/topic were merged.
Number of existing inactive prompts reactivated.
The newly created prompts (excludes skipped, updated, and reactivated).
Show child attributes
Show child attributes