curl --request POST \
--url https://api.surfais.com/v1/orgs/{orgId}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"countries": [
"<string>"
],
"platforms": [],
"tags": [
"<string>"
]
}
'import requests
url = "https://api.surfais.com/v1/orgs/{orgId}/prompts"
payload = {
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"countries": ["<string>"],
"platforms": [],
"tags": ["<string>"]
}
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({
brand_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
text: '<string>',
countries: ['<string>'],
platforms: [],
tags: ['<string>']
})
};
fetch('https://api.surfais.com/v1/orgs/{orgId}/prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"tags": [
"<string>"
],
"countries": [
"<string>"
],
"platforms": [
"<string>"
],
"active": true,
"source": "ui",
"created_by_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {
"existing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {
"tier": "<string>",
"cap": 0,
"attempted": 0
}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}Create a prompt
Creates an ACTIVE prompt for an own brand (brand_id: 400 validation_error with details[].code = "own_brand_only" for a competitor row, 409 brand_archived for an archived own brand) with source: "api" and created_by_key_id set to the calling key. Omitted countries / platforms take the API defaults. An active prompt with the same text (case-insensitive) in the brand is 409 conflict with details.existing_id; an INACTIVE one does not block a create (use the sync to reactivate instead).
curl --request POST \
--url https://api.surfais.com/v1/orgs/{orgId}/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"countries": [
"<string>"
],
"platforms": [],
"tags": [
"<string>"
]
}
'import requests
url = "https://api.surfais.com/v1/orgs/{orgId}/prompts"
payload = {
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"countries": ["<string>"],
"platforms": [],
"tags": ["<string>"]
}
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({
brand_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
text: '<string>',
countries: ['<string>'],
platforms: [],
tags: ['<string>']
})
};
fetch('https://api.surfais.com/v1/orgs/{orgId}/prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"tags": [
"<string>"
],
"countries": [
"<string>"
],
"platforms": [
"<string>"
],
"active": true,
"source": "ui",
"created_by_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {
"existing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {
"tier": "<string>",
"cap": 0,
"attempted": 0
}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"request_id": "<string>"
}Authorizations
A Surfais API key — an organisation key or a partner key. Issued by Surfais; shown once. Rotate by creating a new key, then revoking the old one.
Headers
Optional. 1–255 characters, unique per intended write. Same key + same request → the stored response is replayed with Idempotent-Replayed: true; same key + different request → 409 idempotency_key_reuse; still running → 409 idempotency_key_in_flight. Outside that range → 400 validation_error (invalid_header).
1 - 255Path Parameters
Organisation id. Org keys: the key's own org. Partner keys: any org with an active link. Anything else is 404.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Body
An own brand in the organisation (404 otherwise).
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$The prompt as an end user would type it. At most 500 characters; leading/trailing whitespace is trimmed.
1 - 500Omit for the default, ["GB"].
1 - 29 elementsISO 3166-1 alpha-2 market (case-insensitive). Must be one Surfais scans; otherwise 400 validation_error with details[].code = "unsupported_country".
^[A-Za-z]{2}$Omit for the default — every platform.
1 - 5 elementsScanned AI platform id.
perplexity, chatgpt, gemini, claude, ai_overviews Free-text labels, each at most 100 characters and 256 UTF-8 bytes after trimming, with no control characters. Duplicates are collapsed.
501 - 100Response
The prompt.
Show child attributes
Show child attributes