Aller au contenu principal

Piloter CiteMe depuis un agent IA

Trois surfaces existent. Elles n'ont pas les mêmes clés et ne s'échangent pas.

SurfacePour quoi faireAuthentificationForfait minimal
Serveur MCP hébergé, https://mcp.citeme.ioRecommandé pour un agent : créer des prompts, lancer et lire les audits, lire citations et suggestionsOAuth 2.1 dans le navigateur, ou en Bearer la clé de citeme loginPayant
CLI citemeAnalyse du code, suggestions, llms-txt, agent des Actions. Pas encore de prompts ni de résultats d'audit GEO (cli-citeme#57), voir la CLIclé créée par citeme loginPayant
API publique, https://app.citeme.io/api/v1Intégrations serveur : thèmes et prompts, lancer, suivre et lire des audits question par question, lire les suggestionsclé cm_ du dashboardPayant

Les deux clés sont distinctes : la clé cm_ ne marche que sur /api/v1/projects/*, la clé de citeme login ne marche que sur /api/v1/cli/* et sur le MCP hébergé. Les trois surfaces sont ouvertes sur tous les forfaits payants, fermées sur Free. Forfaits, rôles, durée des clés et clés de CI sont dans Authentification. La connexion du MCP est décrite dans le guide MCP.

Mots-clés et prompts

Un audit s'exécute sur les prompts actifs de la marque (des questions complètes, rangées par thème), jamais sur les mots-clés. POST /projects/:id/keywords ne crée pas de prompt.


Recette avec le MCP hébergé​

Les outils qui écrivent exigent un rôle qui peut modifier. Chaque outil accepte projectId, facultatif quand l'organisation n'a qu'une marque.

  1. Trouver la marque : list_projects.
  2. Choisir le marché : list_markets donne les marchés suivis, qui décident du pays et de la langue des prompts.
  3. Créer un thème : create_topic avec name (et marketId si besoin). Il renvoie l'id du thème.
  4. Créer les prompts : create_prompts avec topicId et prompts, de 1 à 50 questions de 10 à 1000 caractères, envoyées telles quelles. Pour plusieurs thèmes ou marchés d'un coup, import_prompts prend jusqu'à 500 lignes { prompt, topic, market }. Aucun des deux ne lance d'audit. Contrôle : list_topic_prompts.
  5. Lancer l'audit : run_audit avec providers (par défaut chatgpt) et confirm. Avec confirm: false l'outil renvoie un aperçu sans rien dépenser, avec confirm: true il démarre l'audit. Il demande un forfait payant.
  6. Suivre le statut : list_audits (filtre status : PENDING, RUNNING, COMPLETED, FAILED) ou get_audit avec auditId, qui donne la progression, le code d'échec le cas échéant, le nombre de prompts exécutés.
  7. Lire les réponses question par question : get_audit (pagination par limit et offset), ou list_prompts pour chaque question avec cité ou non, position et sentiment, ou get_prompt_detail pour un prompt.
  8. Lire les citations : list_citations pour les passages où la marque est citée, list_cited_sources pour les sources citées par les moteurs, list_suggestions pour les recommandations.

La liste complète et les arguments de chaque outil sont dans la référence des outils du guide MCP.


Recette avec l'API publique​

Avec une clé cm_ qui a le scope write (une clé lecture seule ne permet que les étapes de lecture). Un thème se crée encore dans le dashboard ou par le MCP (create_topic).

BASE=https://app.citeme.io/api/v1
KEY=cm_xxxxxxxxxxxx

# 1. trouver l'id de la marque (un projet dans l'API)
curl -s $BASE/projects -H "Authorization: Bearer $KEY"

# 2. trouver les thèmes, puis créer les prompts d'un thème (50 par appel)
curl -s $BASE/projects/$PROJECT_ID/topics -H "Authorization: Bearer $KEY"
curl -s -X POST $BASE/projects/$PROJECT_ID/prompts \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"topicId":"'$TOPIC_ID'","prompts":["Combien coûtent les frais de notaire dans le neuf ?"]}'

# 3. lancer l'audit sur les moteurs voulus, renvoie { "data": { "auditId", "engines" }, "warnings" }
curl -s -X POST $BASE/projects/$PROJECT_ID/audits \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"providers":["chatgpt","claude","gemini","perplexity","google-aio"]}'

# 4. suivre le statut: chercher l'auditId, attendre COMPLETED ou FAILED
curl -s $BASE/projects/$PROJECT_ID/audits -H "Authorization: Bearer $KEY"

# 5. lire les réponses de chaque question
curl -s $BASE/projects/$PROJECT_ID/audits/$AUDIT_ID -H "Authorization: Bearer $KEY"

Sans providers, l'audit tourne sur les 5 moteurs de base, et le budget du forfait payant couvre ses 50 prompts par marque sur ces 5 moteurs. Lisez toujours warnings : il dit quels moteurs ou quels prompts ont été laissés de côté, et si des réponses ont échoué (partial, failedAnswerCount, errorCode par réponse). Si un audit est déjà en cours, l'étape 3 renvoie son auditId avec reused: true au lieu d'en créer un second. Le détail est décrit dans Audits GEO et Thèmes et prompts.


Erreurs fréquentes​

SymptômeCause
401 sur app.citeme.io/api/v1/projects avec la clé de citeme loginMauvaise clé : il faut une clé cm_ du dashboard
403 ... does not have write permissionsClé cm_ créée en lecture seule : en créer une avec écriture
403 avec feature: "apiAccess"Organisation en Free : l'API demande un forfait payant, voir Forfaits
429 avec code: "quota_exceeded"Audits manuels de la semaine épuisés (5 par marque), ou moins d'audits restants que de moteurs demandés : attendre Retry-After ou demander moins de moteurs
400 avec code: "prompts_required"Aucun prompt actif : en créer, les mots-clés ne comptent pas
Audit COMPLETED avec partial: trueDes appels aux moteurs ont échoué : errorCode par réponse, le score ne couvre que les réponses obtenues