REST API endpoint
POST /v1/competitors — score a rival inside answers you already collect
Registers a brand to detect alongside yours in answers already being collected. It creates no new readings, so it costs nothing.
Karl-Gustav Kallasmaa, Founder & CEOLast updated The request
Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.
curl -X POST https://api.attensira.com/v1/competitors \
-H "Authorization: Bearer atn_live_<your key>" \
-H "Content-Type: application/json" \
-d '{"domain":"rival.com","name":"Rival"}'
Parameters
Every parameter the published reference documents, and nothing it does not.
| Name | In | Type | Default | Notes |
|---|---|---|---|---|
| domain* | body | string | — | A bare hostname such as rival.com. No scheme and no path. |
| name | body | string | — | Optional display name. Defaults to the domain. |
The response (201)
Abbreviated, never invented — this is the shape the published reference documents.
{ "id": "cmp_10b3", "domain": "rival.com", "name": "Rival", "created": true }
What goes wrong, and what it means
The condition on the left, the correct reading of it on the right.
- created comes back false
- The domain was already tracked and nothing changed. The call still succeeded, which makes it safe to run repeatedly from a sync job.
- A full URL is rejected
- The field takes a bare hostname. A scheme or a path is not stripped for you, because guessing which part of a URL identifies a brand is exactly the kind of inference that produces wrong data quietly.
- Your own numbers did not change after adding a rival
- They are not supposed to. Competitor rates use the same denominator as yours, so adding one never moves your own figures.
What this endpoint cannot tell you
The limits are part of the answer, not a disclaimer under it.
- It cannot rank you against the competitor it adds. Both brands are measured as their own mention rate over the same denominator, so the two numbers sit side by side rather than dividing a category, and nothing sums to one hundred percent.
- It cannot see backwards further than the answers you have already collected. A competitor is detected inside answers being gathered for your prompts, so its history begins where your collection does and no earlier.
This is the cheapest useful call in the API. It registers a brand so that the brand is detected in the answers Attensira is already collecting for your prompts, and because no new model readings are involved, it spends nothing.
Why it is free, precisely
Every tracked prompt produces answers on a schedule whether or not you have declared any competitors. Detecting a second brand inside those same answers is a matter of looking at text that already exists in the workspace. There is no additional request to any model, so there is nothing to bill.
That has a practical consequence worth acting on: there is no cost argument for being stingy here. If a name keeps turning up in answers you are reading, register it. The expensive resource in this product is prompts, not competitors.
Send a hostname, not a URL
The domain field takes a bare hostname. No scheme, no path, no trailing slash. A full URL is refused rather than trimmed, and that refusal is deliberate: deciding which part of https://rival.com/uk/pricing?ref=x identifies the brand is exactly the sort of guess that produces plausible, wrong data with nobody noticing.
The optional display name is cosmetic and defaults to the domain. Set it when the domain and the brand differ enough that a chart would be confusing without it.
Idempotent by design
If the domain is already tracked, the response comes back with created set to false and nothing changes. The call still succeeds. That makes it safe to run from a nightly job that reconciles a competitor list held somewhere else, without needing to fetch the current list first or to treat a duplicate as an error.
What the resulting numbers mean, and what they do not
This is where competitor tracking in AI search is most often misread, so it is worth being exact.
A competitor's rate is that brand's own mention rate: how often it was named across the same successful runs your own rate is computed over. Both numbers share a denominator. Neither is a share of a category, and a set of competitor rates does not sum to one hundred percent — nor is it supposed to. Two brands can both be named in the same answer, and frequently are.
Two things follow. First, adding a competitor never moves your own figures, so a change in your rate after an import is a coincidence rather than a consequence. Second, a competitor sitting above you is mentioned more often than you are; it is not ranked above you by anything the product computes, because there is no ranking of brands here to read.
Where the data surfaces
Two places. The competitor area of the analytics endpoint gives the workspace-wide view, one row per rival. The single-prompt endpoint gives the sharper version, listing the rivals observed in one prompt's answers alongside the sources those answers cited — which is usually the more actionable of the two, because it tells you which specific question you are losing and to whom.
Its twin on the other surface
The add_competitor MCP tool takes the same domain and optional name, needs the write scope, and likewise spends nothing. It is a reasonable tool to leave enabled for an assistant, since the worst outcome of an unnecessary call is a competitor row you did not need.
One habit worth building in
Competitor lists rot. A brand that dominated your category's answers eighteen months ago may be gone, and a name that appears in every answer this quarter may not be registered at all. Because registering costs nothing and duplicates are harmless, the maintenance loop is trivially cheap: read the competitor rows in the analytics endpoint, read the rivals listed against your two or three most important prompts, and register anything showing up in the second list that is missing from the first. It takes one read and one write, and it keeps the competitive picture matched to what models are actually saying rather than to what somebody typed into the workspace at setup.
Questions people ask
- Why is adding a competitor free when adding a prompt is not?
- Because it creates no new readings. A competitor is detected inside answers that were already going to be collected for your prompts, so there is no extra model call to pay for.
- Does adding a competitor change my own rates?
- No. Competitor rates use the same denominator as yours, so adding one never changes your numbers.
- What format does the domain take?
- A bare hostname, with no scheme and no path. Send rival.com rather than https://rival.com/pricing.
- Is it safe to call this from a nightly sync?
- Yes. A domain that is already tracked comes back with created set to false, and nothing changes.
- Where do the resulting numbers show up?
- In the competitor area of the analytics endpoint for a workspace-wide view, and inline on the single-prompt endpoint for the rivals seen against one prompt.
Sources
Every factual statement above, with the page it came from and the date that page was read.
The Attensira API reference states that registering a competitor creates no new readings and so costs nothing, because the brand is detected in answers already being collected.
docs.attensira.com · retrieved
“It creates no new readings, so it costs nothing.”
The API reference states that competitor rates use the same denominator as the workspace's own rates, so adding a competitor never changes your numbers.
docs.attensira.com · retrieved
“Competitor rates use the same denominator as your own, so adding one never changes your numbers.”