DocumentationRéférence de l'API
Mots-clés
Les mots-clés d'un site : les lister, les ajouter, les modifier et les supprimer.
Chaque opération ci-dessous est aussi un outil MCP, sous le même nom. Les opérations marquées Gratuit ne coûtent rien ; celles marquées Facturé utilisent les crédits de l'espace, comme dans l'app (Ce que ça coûte).
| Opération | Appel | |
|---|---|---|
| Lister les mots-clés | GET /sites/{siteId}/keywords | Gratuit |
| Ajouter un mot-clé | POST /sites/{siteId}/keywords | Gratuit |
| Modifier un mot-clé | PATCH /sites/{siteId}/keywords/{keywordId} | Gratuit |
| Supprimer un mot-clé | DELETE /sites/{siteId}/keywords/{keywordId} | Gratuit |
Lister les mots-clés
/sites/{siteId}/keywordsGratuitLes mots-clés cibles du site, issus de son analyse ou ajoutés à la main, avec leur volume, leur difficulté et leur position actuelle.
- Le texte est renvoyé tel qu'il est enregistré, dans la langue où il a été écrit (source_lang ; null = la langue du contenu du site). L'app le traduit à l'affichage ; l'API non.
Outil MCP list_keywords
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
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"
}
]
}Ajouter un mot-clé
/sites/{siteId}/keywordsGratuitAjouter un mot-clé cible au site.
- Enregistré tel quel, comme mot-clé manuel : aucune donnée de mot-clé n'est récupérée (rien n'est facturé). Renvoie le mot-clé.
Outil MCP add_keyword
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
keywordobligatoire | string | Le mot-clé.1–255 caractères |
volumefacultatif | string | null | Son volume de recherche mensuel, s'il est connu. |
difficultyfacultatif | string | null | Sa difficulté, de 0 à 100, si elle est connue. |
intentfacultatif | string | null | informational, commercial, transactional ou navigational. |
priorityfacultatif | string | high, medium (par défaut) ou low.high | medium | low |
rationalefacultatif | string | null | Pourquoi le viser. |
source_langfacultatif | string | La langue dans laquelle le texte est écrit (par ex. "fr", "en"). Omise : la langue du contenu du site.2–5 caractères |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/keywords \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"keyword": "…"}'Répond 201 avec { "data": … }.
Modifier un mot-clé
/sites/{siteId}/keywords/{keywordId}GratuitModifier un mot-clé cible : le mot-clé, ses chiffres, son intention, sa priorité ou sa justification.
- Renvoie le mot-clé tel qu'il est désormais.
Outil MCP update_keyword
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
keywordIddans le chemin | string | Son identifiant. |
keywordfacultatif | string | 1–255 caractères |
volumefacultatif | string | null | |
difficultyfacultatif | string | null | |
intentfacultatif | string | null | |
priorityfacultatif | string | high | medium | low |
rationalefacultatif | string | null | |
source_langfacultatif | string | La langue du nouveau mot-clé / de la nouvelle justification. Ignorée quand aucun des deux ne change.2–5 caractères |
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": "…"}'Répond 200 avec { "data": … }.
Supprimer un mot-clé
/sites/{siteId}/keywords/{keywordId}GratuitRetirer un mot-clé cible du site.
Outil MCP delete_keyword
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
keywordIddans le chemin | string | Son identifiant. |
curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/keywords/{keywordId} \
-H "Authorization: Bearer sk_live_…"Répond 204 avec { "data": … }.
Une question sans réponse ici ? Écrivez-nous.

