# Piloter CiteMe depuis un agent IA

> Quelle surface utiliser (MCP hébergé, CLI, API publique), quelle clé fonctionne où, et la recette pour créer des prompts, lancer un audit et lire les réponses.

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](https://github.com/CiteMe/cli-citeme/issues/57)), voir la [CLI](./cli/index.md) | 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](./api/authentication.md). La connexion du MCP est décrite dans [le guide MCP](./mcp/index.md).

:::warning 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.

1. **Trouver le projet** : `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 le forfait Pro ou Expert.
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](./mcp/tools.md) du [guide MCP](./mcp/index.md).

---

## 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.

```bash
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](./api/audits.md).

---

## 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 |