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).
| Operation | Call | |
|---|---|---|
| List keywords | GET /sites/{siteId}/keywords | Free |
| Add keyword | POST /sites/{siteId}/keywords | Free |
| Update keyword | PATCH /sites/{siteId}/keywords/{keywordId} | Free |
| Delete keyword | DELETE /sites/{siteId}/keywords/{keywordId} | Free |
List keywords
/sites/{siteId}/keywordsFreeThe 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
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/keywords \
-H "Authorization: Bearer sk_live_…"{
"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
/sites/{siteId}/keywordsFreeAdd 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
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
keywordrequired | string | The keyword.1–255 characters |
volumeoptional | string | null | Its monthly search volume, if known. |
difficultyoptional | string | null | Its difficulty, 0–100, if known. |
intentoptional | string | null | informational, commercial, transactional or navigational. |
priorityoptional | string | high, medium (default) or low.high | medium | low |
rationaleoptional | string | null | Why to target it. |
source_langoptional | string | The language the text is written in (e.g. "fr", "en"). Omitted: the site’s content language.2–5 characters |
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
/sites/{siteId}/keywords/{keywordId}FreeChange a target keyword: the keyword, its figures, intent, priority or rationale.
- Answers the keyword as it now is.
MCP tool update_keyword
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
keywordIdin the path | string | Its id. |
keywordoptional | string | 1–255 characters |
volumeoptional | string | null | |
difficultyoptional | string | null | |
intentoptional | string | null | |
priorityoptional | string | high | medium | low |
rationaleoptional | string | null | |
source_langoptional | string | The language of the new keyword / rationale. Ignored when neither changes.2–5 characters |
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
/sites/{siteId}/keywords/{keywordId}FreeRemove a target keyword from the site.
MCP tool delete_keyword
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
keywordIdin the path | string | Its id. |
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.

