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érationAppel
Lister les mots-clésGET /sites/{siteId}/keywordsGratuit
Ajouter un mot-cléPOST /sites/{siteId}/keywordsGratuit
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

GET/sites/{siteId}/keywordsGratuit

Les 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

ArgumentTypeDescription
siteIddans le cheminstringSon identifiant.
Requête
curl https://app.semchat.io/api/v1/sites/{siteId}/keywords \
  -H "Authorization: Bearer sk_live_…"
Réponse · 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"
    }
  ]
}

Ajouter un mot-clé

POST/sites/{siteId}/keywordsGratuit

Ajouter 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

ArgumentTypeDescription
siteIddans le cheminstringSon identifiant.
keywordobligatoirestringLe mot-clé.1–255 caractères
volumefacultatifstring | nullSon volume de recherche mensuel, s'il est connu.
difficultyfacultatifstring | nullSa difficulté, de 0 à 100, si elle est connue.
intentfacultatifstring | nullinformational, commercial, transactional ou navigational.
priorityfacultatifstringhigh, medium (par défaut) ou low.high | medium | low
rationalefacultatifstring | nullPourquoi le viser.
source_langfacultatifstringLa langue dans laquelle le texte est écrit (par ex. "fr", "en"). Omise : la langue du contenu du site.2–5 caractères
Requête
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é

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

Modifier 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

ArgumentTypeDescription
siteIddans le cheminstringSon identifiant.
keywordIddans le cheminstringSon identifiant.
keywordfacultatifstring1–255 caractères
volumefacultatifstring | null
difficultyfacultatifstring | null
intentfacultatifstring | null
priorityfacultatifstringhigh | medium | low
rationalefacultatifstring | null
source_langfacultatifstringLa langue du nouveau mot-clé / de la nouvelle justification. Ignorée quand aucun des deux ne change.2–5 caractères
Requête
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é

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

Retirer un mot-clé cible du site.

Outil MCP delete_keyword

ArgumentTypeDescription
siteIddans le cheminstringSon identifiant.
keywordIddans le cheminstringSon identifiant.
Requête
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.

Prêt à faire décoller votre site ?

Posez votre première question - semchat vous répond avec un plan d'action clair, en quelques secondes.

Gratuit · sans inscription · en 5 secondes