Browse the documentation
Add Prompts to Track
Add prompts to track for a brand across the chosen AI platforms and queue the first crawl. Requires a write-enabled API key.
POST
/prompts
Request body
Send as application/json. This endpoint needs a write-enabled API key.
| Field | Type | Description |
|---|---|---|
| brand required | string | Tracked brand name. |
| prompts required | array of string | The prompts to track. Blank and repeated ones don't count toward the maximum. More than the maximum, or a prompt over the length limit, is a 400. Allowed: 1–50 items, each up to 2,000 characters. |
| llms required | array of string | Platform slugs the plan allows, e.g. ['openai', 'claude']. Allowed: 1 or more items. |
| country | string | ISO alpha-2 code; 'ZZ' or omitted = Global. An unsupported code is a 400, not Global. |
| tags | array of string | Tags to attach to every prompt in the call. Repeats, ignoring case and spacing, don't count toward the maximum. More than the maximum, or a tag over the length limit, is a 400. Allowed: up to 10 items, each up to 100 characters. |
Example request
curl -X POST -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"brand": "Acme",
"prompts": [
"best crm software"
],
"llms": [
"openai"
]
}' \
"https://api.mentionbird.ai/api/v1/prompts"
Responses
- 200
- Prompts added and crawl queued.
- 400
- Validation error — check the message in `error.message`.
- 401
- Unauthorized — missing, invalid or revoked bearer token.
- 403
- Forbidden — the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit.
- 404
- Not found — the brand, prompt or resource does not exist.
- 405
- Method not allowed.
- 429
- Too many requests — over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.
- 500
- Internal error — logged; retry is safe for reads.