Piloter CiteMe depuis un agent IA
Trois surfaces existent. Elles n'ont pas les mêmes clés et ne s'échangent pas.
| Surface | Pour quoi faire | Authentification | Forfait minimal |
|---|---|---|---|
Serveur MCP hébergé, https://mcp.citeme.io | Recommandé pour un agent : créer des prompts, lancer et lire les audits, lire citations et suggestions | OAuth 2.1 dans le navigateur, ou en Bearer la clé de citeme login | Payant |
CLI citeme | Analyse du code, suggestions, llms-txt, agent des Actions. Pas encore de prompts ni de résultats d'audit GEO (cli-citeme#57), voir la CLI | clé créée par citeme login | Payant |
API publique, https://app.citeme.io/api/v1 | Intégrations serveur : thèmes et prompts, lancer, suivre et lire des audits question par question, lire les suggestions | clé cm_ du dashboard | Payant |
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.
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.
- Trouver la marque :
list_projects. - Choisir le marché :
list_marketsdonne les marchés suivis, qui décident du pays et de la langue des prompts. - Créer un thème :
create_topicavecname(etmarketIdsi besoin). Il renvoie l'id du thème. - Créer les prompts :
create_promptsavectopicIdetprompts, de 1 à 50 questions de 10 à 1000 caractères, envoyées telles quelles. Pour plusieurs thèmes ou marchés d'un coup,import_promptsprend jusqu'à 500 lignes{ prompt, topic, market }. Aucun des deux ne lance d'audit. Contrôle :list_topic_prompts. - Lancer l'audit :
run_auditavecproviders(par défautchatgpt) etconfirm. Avecconfirm: falsel'outil renvoie un aperçu sans rien dépenser, avecconfirm: trueil démarre l'audit. Il demande un forfait payant. - Suivre le statut :
list_audits(filtrestatus:PENDING,RUNNING,COMPLETED,FAILED) ouget_auditavecauditId, qui donne la progression, le code d'échec le cas échéant, le nombre de prompts exécutés. - Lire les réponses question par question :
get_audit(pagination parlimitetoffset), oulist_promptspour chaque question avec cité ou non, position et sentiment, ouget_prompt_detailpour un prompt. - Lire les citations :
list_citationspour les passages où la marque est citée,list_cited_sourcespour les sources citées par les moteurs,list_suggestionspour 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ôme | Cause |
|---|---|
401 sur app.citeme.io/api/v1/projects avec la clé de citeme login | Mauvaise clé : il faut une clé cm_ du dashboard |
403 ... does not have write permissions | Clé 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: true | Des appels aux moteurs ont échoué : errorCode par réponse, le score ne couvre que les réponses obtenues |