DocumentationAPI reference

Keywords

A site’s keywords: list, add, change and delete them.

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 keywordsGET /sites/{siteId}/keywordsFree
Add keywordPOST /sites/{siteId}/keywordsFree
Update keywordPATCH /sites/{siteId}/keywords/{keywordId}Free
Delete keywordDELETE /sites/{siteId}/keywords/{keywordId}Free

List keywords

GET/sites/{siteId}/keywordsFree

The site’s target keywords, from its analysis or added by hand, with their volume, difficulty and current position.

  • Text is returned as stored, in the language it was written in (source_lang; null = the site’s content language). The app translates it on display; the API does not.

MCP tool list_keywords

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/keywords \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "data": [
    {
      "id": "01a15ea4-c1e0-7957-b667-9b025ed3641e",
      "keyword": "agence seo lyon",
      "volume": 1900,
      "difficulty": 45,
      "cpc": 1.8,
      "competition": 40,
      "current_position": 4,
      "traffic": 475,
      "url": "https://alpha.example.com/services",
      "intent": "commercial",
      "priority": "high",
      "rationale": "Opportunité sur « agence seo lyon ».",
      "source": "auto",
      "source_lang": "fr",
      "created_at": "2026-10-21T13:26:58.000Z"
    },
    {
      "id": "01a15ea4-c1e0-7e93-9a50-38742b693311",
      "keyword": "audit seo",
      "volume": 2400,
      "difficulty": 60,
      "cpc": 1.8,
      "competition": 40,
      "current_position": 12,
      "traffic": 200,
      "url": "https://alpha.example.com/services",
      "intent": "commercial",
      "priority": "high",
      "rationale": "Opportunité sur « audit seo ».",
      "source": "auto",
      "source_lang": "fr",
      "created_at": "2026-10-21T13:26:58.000Z"
    }
  ]
}

Add keyword

POST/sites/{siteId}/keywordsFree

Add a target keyword to the site.

  • Stored as given, as a manual keyword: no keyword data is fetched (nothing billed). Answers the keyword.

MCP tool add_keyword

ArgumentTypeDescription
siteIdin the pathstringIts id.
keywordrequiredstringThe keyword.1–255 characters
volumeoptionalstring | nullIts monthly search volume, if known.
difficultyoptionalstring | nullIts difficulty, 0–100, if known.
intentoptionalstring | nullinformational, commercial, transactional or navigational.
priorityoptionalstringhigh, medium (default) or low.high | medium | low
rationaleoptionalstring | nullWhy to target it.
source_langoptionalstringThe language the text is written in (e.g. "fr", "en"). Omitted: the site’s content language.2–5 characters
Request
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/keywords \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "…"}'

Answers 201 with { "data": … }.

Update keyword

PATCH/sites/{siteId}/keywords/{keywordId}Free

Change a target keyword: the keyword, its figures, intent, priority or rationale.

  • Answers the keyword as it now is.

MCP tool update_keyword

ArgumentTypeDescription
siteIdin the pathstringIts id.
keywordIdin the pathstringIts id.
keywordoptionalstring1–255 characters
volumeoptionalstring | null
difficultyoptionalstring | null
intentoptionalstring | null
priorityoptionalstringhigh | medium | low
rationaleoptionalstring | null
source_langoptionalstringThe language of the new keyword / rationale. Ignored when neither changes.2–5 characters
Request
curl -X PATCH https://app.semchat.io/api/v1/sites/{siteId}/keywords/{keywordId} \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "…"}'

Answers 200 with { "data": … }.

Delete keyword

DELETE/sites/{siteId}/keywords/{keywordId}Free

Remove a target keyword from the site.

MCP tool delete_keyword

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

Answers 204 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