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).

OperationCall
List competitorsGET /sites/{siteId}/competitorsFree
Add competitorPOST /sites/{siteId}/competitorsFree
Delete competitorDELETE /sites/{siteId}/competitors/{competitorId}Free
Profile competitorPOST /sites/{siteId}/competitors/{competitorId}/profileBilled
Get competitor backlinksGET /sites/{siteId}/competitors/{competitorId}/backlinksBilled

List competitors

GET/sites/{siteId}/competitorsFree

The site’s competitors, with their profile once analysed.

MCP tool list_competitors

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/competitors \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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

POST/sites/{siteId}/competitorsFree

Add 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

ArgumentTypeDescription
siteIdin the pathstringIts id.
urlrequiredstringThe competitor’s address.1–500 characters
nameoptionalstringup to 255 characters
auto_analyzeoptionalbooleanProfile it in the background (billed). Skipped without credits.
Request
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

DELETE/sites/{siteId}/competitors/{competitorId}Free

Remove a competitor from the site’s set.

MCP tool delete_competitor

ArgumentTypeDescription
siteIdin the pathstringIts id.
competitorIdin the pathstringIts id.
Request
curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId} \
  -H "Authorization: Bearer sk_live_…"

Answers 204 with { "data": … }.

Profile competitor

POST/sites/{siteId}/competitors/{competitorId}/profileBilled

Analyse 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

ArgumentTypeDescription
siteIdin the pathstringIts id.
competitorIdin the pathstringIts id.
backgroundoptionalbooleanAnswer at once (202, status analyzing) and store the profile when it lands: read list_competitors for it.
localeoptionalstringThe language to write the profile in (fr, en, es, de, pt, it). Default: the key creator’s.2–5 characters
Request
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": … }.

A question this doesn’t answer? Write to us.

Ready to get your site off the ground?

Ask your first question - semchat replies with a clear action plan in seconds.

Free · no sign-up · takes 5 seconds