DocumentationAPI reference
Competitors
A site’s competitors, their analysis and their backlinks.
Every operation below is also an MCP tool, under the same name. Free operations cost nothing; Billed ones use the workspace’s credits, as in the app (What it costs).
| Operation | Call | |
|---|---|---|
| List competitors | GET /sites/{siteId}/competitors | Free |
| Add competitor | POST /sites/{siteId}/competitors | Free |
| Delete competitor | DELETE /sites/{siteId}/competitors/{competitorId} | Free |
| Profile competitor | POST /sites/{siteId}/competitors/{competitorId}/profile | Billed |
| Get competitor backlinks | GET /sites/{siteId}/competitors/{competitorId}/backlinks | Billed |
List competitors
/sites/{siteId}/competitorsFreeThe site’s competitors, with their profile once analysed.
MCP tool list_competitors
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/competitors \
-H "Authorization: Bearer sk_live_…"{
"data": [
{
"id": "01a15ea4-c1e0-7285-bdde-d36e70d2d1b9",
"url": "https://comp1.example.com",
"name": "Concurrent Un",
"source": "auto",
"profiled_at": "2026-10-21T13:26:58.000Z",
"metrics": {
"traffic": 5200,
"keywords": 400,
"overlap": 40,
"reason": "Mêmes mots-clés à Lyon."
},
"profile": {
"summary": "Concurrent Un accompagne les PME.",
"positioning": "Agence généraliste.",
"topics": [
"SEO",
"SEA"
],
"strengths": [
"Notoriété"
],
"tech": [
"wordpress"
],
"pageCount": 24
}
},
{
"id": "01a15ea4-c1e0-7042-931d-3fa2cb1f4ffc",
"url": "https://comp2.example.com",
"name": "Concurrent Deux",
"source": "auto",
"profiled_at": "2026-10-21T13:26:58.000Z",
"metrics": {
"traffic": 4200,
"keywords": 350,
"overlap": 30,
"reason": "Mêmes mots-clés à Lyon."
},
"profile": {
"summary": "Concurrent Deux accompagne les PME.",
"positioning": "Agence généraliste.",
"topics": [
"SEO",
"SEA"
],
"strengths": [
"Notoriété"
],
"tech": [
"wordpress"
],
"pageCount": 24
}
}
]
}Add competitor
/sites/{siteId}/competitorsFreeAdd a competitor, and optionally profile it (billed).
- Answers its id and
analyzing: false when no analysis was started (none asked for, or no credits; the competitor is saved all the same).
MCP tool add_competitor
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
urlrequired | string | The competitor’s address.1–500 characters |
nameoptional | string | up to 255 characters |
auto_analyzeoptional | boolean | Profile it in the background (billed). Skipped without credits. |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/competitors \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Answers 201 with { "data": … }.
Delete competitor
/sites/{siteId}/competitors/{competitorId}FreeRemove a competitor from the site’s set.
MCP tool delete_competitor
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
competitorIdin the path | string | Its id. |
curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId} \
-H "Authorization: Bearer sk_live_…"Answers 204 with { "data": … }.
Profile competitor
/sites/{siteId}/competitors/{competitorId}/profileBilledAnalyse a competitor (a shallow crawl of its site and an AI summary: what it does, its positioning, topics, strengths, its gaps against your site) and store it on the competitor.
- Billed like the same analysis in the app (an AI call). 402 INSUFFICIENT_TOKENS without credits.
- Without background, waits for the profile (up to a few minutes) and answers the competitor with it.
MCP tool profile_competitor
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
competitorIdin the path | string | Its id. |
backgroundoptional | boolean | Answer at once (202, status analyzing) and store the profile when it lands: read list_competitors for it. |
localeoptional | string | The language to write the profile in (fr, en, es, de, pt, it). Default: the key creator’s.2–5 characters |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId}/profile \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"background": true}'Answers 200 with { "data": … }.
Get competitor backlinks
/sites/{siteId}/competitors/{competitorId}/backlinksBilledA competitor’s backlink numbers: rank (0–100), referring domains, backlinks, spam score.
- Free when the site’s stored backlink profile (get_backlinks) already covers this competitor; otherwise one billed data call, as in the app.
- 402 INSUFFICIENT_TOKENS without credits when a billed call would be needed.
MCP tool get_competitor_backlinks
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
competitorIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId}/backlinks \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
A question this doesn’t answer? Write to us.

