Add Competitor
Track a new competitor for a domain — add it as a dedicated brand you follow, or as a plain tracked entry.
curl --request POST \
--url 'https://api.aiclicks.io/api/v1/competitors' \
--header 'Authorization: Bearer ak_live_xxx' \
--header 'Content-Type: application/json' \
--data '{
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"competitor_domain": "acmerival.com",
"competitor_name": "Acme Rival",
"is_dedicated": true,
"competitor_variations": ["Acme", "AcmeRival Inc"]
}'
import httpx, os
resp = httpx.post(
"https://api.aiclicks.io/api/v1/competitors",
json={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"competitor_domain": "acmerival.com",
"competitor_name": "Acme Rival",
"is_dedicated": True,
"competitor_variations": ["Acme", "AcmeRival Inc"],
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
competitor = resp.json()["data"]["competitor"]
print(competitor["id"], competitor["website"])
const resp = await fetch("https://api.aiclicks.io/api/v1/competitors", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AICLICKS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
domain_id: "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
competitor_domain: "acmerival.com",
competitor_name: "Acme Rival",
is_dedicated: true,
competitor_variations: ["Acme", "AcmeRival Inc"],
}),
});
const { data } = await resp.json();
console.log(data.competitor.id, data.competitor.website);
{
"data": {
"success": true,
"message": "Competitor added successfully",
"competitor": {
"id": "f6a7b8c9-3333-4eee-8fff-000000000001",
"created_at": "2026-08-18T10:00:11.218Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Acme Rival",
"website": "acmerival.com",
"is_dedicated": true,
"active": true,
"updated_at": "2026-08-18T10:00:11.218Z",
"variations": ["Acme", "AcmeRival Inc"]
}
},
"generated_at": "2026-08-18T10:00:11.218Z"
}
{
"detail": "Maximum 10 dedicated competitors allowed per domain"
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "API access is not enabled for this team. Contact support@aiclicks.io."
}
{
"detail": "Domain not found"
}
{
"detail": "Competitor already exists for this domain"
}
{
"detail": "Too many requests. Please try again later."
}
Adds a competitor to the domain's tracking set. Send the competitor's domain and display name; optionally mark it dedicated (is_dedicated: true) to promote it into the brands you actively follow. Dedicated competitors count against your plan's dedicated-competitor limit — adding one does not consume a separate credit, but exceeding the limit returns 400.
Pair this with ``, which surfaces untracked brands the models mention, then promote the ones worth following by adding them here.
** defaults to**** over REST.** A bare add creates a plain tracked competitor, not a dedicated one — set is_dedicated: true explicitly to follow it. (The aiclicks MCP add_competitor tool defaults this to true; the raw REST default is false.)
Authorizations
Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.
Optional UUID for log correlation. If omitted, we generate one and echo it back in the response.
Body parameters
UUID of the domain to add the competitor to. Find domains via ``.
The competitor's website. Normalized to a registered domain (host only, scheme and www. stripped) before storage — https://www.acmerival.com/ becomes acmerival.com. A value that normalizes to empty returns 400.
Display name for the competitor, e.g. "Acme Rival".
true promotes the competitor to a dedicated (actively tracked) brand, counting against the plan's dedicated-competitor limit. Defaults to false — a plain tracked entry. Adding a dedicated competitor does not consume a separate credit.
Tracking state. true = actively tracked, false = suggested but not yet tracked. Defaults to true.
Alternate names / spellings to match against model answers. Free text, deduped case-insensitively. Defaults to an empty array.
Response
The add result.
true when the competitor was created.
Human-readable status, "Competitor added successfully".
The stored competitor row.
ISO-8601 timestamp of when the server produced this response.
Response headers
| Header | Description |
|---|---|
X-Request-Id | Unique request id. Echoes incoming if you set one. |
X-RateLimit-Limit | Max requests per minute for this key. |
X-RateLimit-Remaining | Requests remaining in current minute. |
X-RateLimit-Reset | Unix epoch seconds when the window resets. |
Idempotency
A competitor is unique per (domain_id, website). Re-adding the same website returns 409 rather than creating a duplicate — update the existing row through the dashboard if you need to change its name, variations, or dedicated flag.
Errors
The dedicated-competitor limit for the domain has been reached (Maximum N dedicated competitors allowed per domain), or competitor_domain normalized to an empty host. Missing or malformed required fields return 422.
Missing, malformed, or revoked API key.
Team's developer_access flag is off, the domain belongs to a team your API key is not scoped to, or your allowed_domains allowlist excludes it.
domain_id is malformed, does not exist, or your user is not a member of its team.
A competitor with this competitor_domain already exists for the domain.
Rate limit exceeded. Inspect the Retry-After header for how long to wait.