Add Prompts (Bulk)
Add up to 100 tracked prompts to a domain in one call, with optional topic and tag names.
curl --request POST \
--url https://api.aiclicks.io/api/v1/prompts/bulk \
--header 'Authorization: Bearer ak_live_xxx' \
--header 'Content-Type: application/json' \
--data '{
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"prompts": [
{ "text": "best CRM for small business", "topics": ["CRM"], "tags": ["Commercial"] },
{ "text": "how to migrate from spreadsheets to a CRM", "topics": ["CRM", "Migration"] }
]
}'
import httpx, os
resp = httpx.post(
"https://api.aiclicks.io/api/v1/prompts/bulk",
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
json={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"prompts": [
{"text": "best CRM for small business", "topics": ["CRM"], "tags": ["Commercial"]},
{"text": "how to migrate from spreadsheets to a CRM", "topics": ["CRM", "Migration"]},
],
},
)
resp.raise_for_status()
data = resp.json()["data"]
print(len(data["added"]), "added;", data["duplicates"], "skipped")
const resp = await fetch("https://api.aiclicks.io/api/v1/prompts/bulk", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AICLICKS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
domain_id: "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
prompts: [
{ text: "best CRM for small business", topics: ["CRM"], tags: ["Commercial"] },
{ text: "how to migrate from spreadsheets to a CRM", topics: ["CRM", "Migration"] },
],
}),
});
const { data } = await resp.json();
console.log(data.added.length, data.duplicates);
{
"data": {
"added": [
{
"id": "21c1f9aa-9b6d-4e3a-8a31-2b0c0e1f2a3b",
"text": "best CRM for small business",
"estimated_search_volume": 8100,
"created_at": "2026-11-09T10:00:11.118000+00:00",
"topics": ["CRM"],
"tags": ["Commercial"]
}
],
"duplicates": ["how to migrate from spreadsheets to a CRM"],
"errors": []
},
"generated_at": "2026-11-09T10:00:11.218000+00:00"
}
{
"detail": "Not enough remaining prompts. You have 1 prompts but need 2."
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "Access denied: User is not a member of the team that owns this domain"
}
{
"detail": [
{
"type": "too_long",
"loc": ["body", "prompts"],
"msg": "List should have at most 100 items after validation, not 101"
}
]
}
{
"detail": "Too many requests. Please try again later."
}
Adds up to 100 prompts to one domain in one request. Each prompt can have topic names and tag names. The new prompts join the analysis of the domain immediately.
This endpoint takes names, not IDs, for topics and tags. If a topic name does not exist, the API creates the topic. If a tag name does not exist, the API skips that tag. If a prompt gets no known tag, the API gives it the default tags of the domain.
The API skips a prompt that has the same text as an active prompt. The API also skips a prompt that has the same text as an earlier prompt in the same request. The response lists the skipped texts in duplicates.
To add one prompt with topic and tag IDs, use POST /api/v1/prompts.
This is a billed write. Each added prompt uses one prompt credit from the team of the domain. The API checks the credits before it adds a prompt. If the team does not have a credit for each new prompt, the call returns 400 and the API adds no prompts.
Authorizations
Your API key in the format Bearer ak_live_<your-key>. Create a key in the dashboard under Settings → Developers. The key must have access to the team that owns domain_id.
Must be application/json.
Optional UUID for log correlation. If you do not send it, the API makes one and returns it in the response.
Body parameters
UUID of the domain. Find domains with GET /api/v1/domains.
The prompts to add. Send 1 to 100 items.
Response
The prompts that the API added. Each item has id, text, estimated_search_volume, created_at, topics (names) and tags (names).
The texts that the API skipped. Each text is the same as an active prompt or as an earlier item in the request. Skipped prompts use no credit.
Other items that failed. Each item is { "query": "<text>", "error": "<reason>" }, for example "Empty prompt text". Failed items use no credit.
ISO-8601 time when the server made this response.
Side effects
- The API uses one prompt credit for each added prompt.
- The added prompts join the next analysis run.
- The API creates topics for unknown topic names.
- The API clears the cache of
GET /api/v1/prompts,GET /api/v1/tagsandGET /api/v1/topicsfor the domain.
Errors
The team does not have a credit for each new prompt. The message gives the numbers, for example "Not enough remaining prompts. You have 1 prompts but need 2." The API adds no prompts.
The API key is missing, malformed or revoked.
The caller is not a member of the team of the domain. Or the API key has no access to this domain. Or the plan of the team does not include API access (the Starter plan does not).
domain_id is not a valid UUID, or the domain does not exist.
The body is not valid. For example, prompts is empty, has more than 100 items, or a required field is missing.
You sent too many requests. Read the Retry-After header to know how long to wait.