Generate prompt suggestions
curl --request POST \
--url https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"source": "<string>",
"keywordId": "<string>",
"refill": true
}
'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs"
payload = {
"source": "<string>",
"keywordId": "<string>",
"refill": True
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({source: '<string>', keywordId: '<string>', refill: true})
};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"status": "<string>",
"source": "<string>",
"keywordId": {},
"recommendations": {},
"createdAt": "<string>",
"completedAt": {}
}Prompt suggestions
Generate prompt suggestions
Start a Prompt Studio generation for a workspace or one topic. It uses no customer credits, returns 202, and is limited per workspace over 24 hours.
POST
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
prompt-suggestions
/
runs
Generate prompt suggestions
curl --request POST \
--url https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"source": "<string>",
"keywordId": "<string>",
"refill": true
}
'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs"
payload = {
"source": "<string>",
"keywordId": "<string>",
"refill": True
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({source: '<string>', keywordId: '<string>', refill: true})
};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/prompt-suggestions/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"status": "<string>",
"source": "<string>",
"keywordId": {},
"recommendations": {},
"createdAt": "<string>",
"completedAt": {}
}Starts a Prompt Studio generation. The request returns
See Error codes for authentication, plan, idempotency and server errors. A token without write access returns
202 with the generation
and a Location header. Poll Get a suggestion generation,
or subscribe an integration webhook to
prompt_suggestions.ready and
prompt_suggestions.failed.
Generation uses no customer credits. It is limited to 3 workspace generations
and 10 topic generations per workspace over a rolling 24 hours. At most one
workspace generation and one generation per topic can run at a time. A request
for the same running scope returns 409 RESOURCE_BUSY.
Requires an active Business, Agency Business or Enterprise plan, and an API token with write access enabled by an Owner or Manager. See Writing data for activation, idempotency, conditional requests and error handling.
Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.
Response
Returns202 with the generation.
Synthetic request and response
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/prompt-suggestions/runs" \
-H "Authorization: Bearer $QWAIRY_API_TOKEN" \
-H "Idempotency-Key: suggestions-001" \
-H "Content-Type: application/json" \
-d '{"source":"manual"}'
{
"id": "bbbbbbbb-0000-4000-8000-000000000000",
"status": "PENDING",
"source": "manual",
"keywordId": null,
"recommendations": null,
"createdAt": "2026-10-12T09:00:00.000Z",
"completedAt": null
}
Errors
| Status | Code | Cause |
|---|---|---|
400 | INVALID_REQUEST | keywordId is missing with source: topic, or a value is invalid |
404 | RESOURCE_NOT_FOUND | The workspace or topic is missing or inaccessible |
409 | RESOURCE_BUSY | A generation for this scope is running; error.details.suggestionRunId identifies it |
409 | QUOTA_EXCEEDED | The rolling allowance is exhausted; error.details.resetsAt gives the reset when known |
409 | CONFLICT | A topic needs an existing pool, or no monitored topic needs a refill |
403 API_KEY_READ_ONLY. On 429, honor Retry-After. If the write limiter is unavailable or writes are suspended, the request returns 503 SERVICE_UNAVAILABLE and nothing changes.
