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`	Starter
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`	Starter
API publique, `https://app.citeme.io/api/v1`	Intégrations serveur : lister, lancer et lire des audits, lire les suggestions	clé `cm_` du dashboard	Pro

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é. Détails 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 du projet (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'un projet.

Trouver le projet : list_projects.
Choisir le marché : list_markets donne les marchés suivis, qui décident du pays et de la langue des prompts.
Créer un thème : create_topic avec name (et marketId si besoin). Il renvoie l'id du thème.
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.
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 le forfait Pro ou Expert.
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.
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.
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 1, 3 et 4). Les prompts ne se créent pas par cette API : créez-les avant, dans le dashboard ou par le MCP.

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

# 1. trouver l'id du projet
curl -s $BASE/projects -H "Authorization: Bearer $KEY"

# 2. lancer l'audit, renvoie { "data": { "auditId", "jobId" } }
curl -s -X POST $BASE/projects/$PROJECT_ID/audits \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1","region":"fr"}'

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

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

Si un audit est déjà en cours, l'étape 2 renvoie son auditId avec reused: true au lieu d'en créer un second. Le détail (queries[].prompt, response, provider, cited, sources, citations, analytics) est décrit dans Audits GEO.

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 ... requires a platform subscription`	Forfait sans accès API : Pro ou Expert requis
`500 Failed to start audit`	Quota d'audits épuisé ou modèle non disponible dans le forfait
Audit terminé mais `queries` vide	Aucun prompt actif : en créer, les mots-clés ne comptent pas

Recette avec le MCP hébergé​

Recette avec l'API publique​

Erreurs fréquentes​

Recette avec le MCP hébergé

Recette avec l'API publique

Erreurs fréquentes