Thèmes et prompts

Les prompts sont les questions qu'un audit pose aux moteurs IA. Chaque prompt appartient à un thème, et le marché du thème décide de la langue et du pays dans lesquels il est posé. Lire demande une clé cm_ d'un forfait payant, créer ou archiver demande en plus le scope write (voir Authentification).

Les mots-clés ne sont pas des prompts

/keywords ne crée pas de prompt et aucun audit ne le lit. Les questions d'audit se créent ici.

---

GET /projects/:id/topics

Les thèmes de la marque, avec le nombre de prompts actifs de chacun. C'est là que se trouvent les topicId dont la création de prompts a besoin.

Paramètre	Description
status	ACTIVE, SUGGESTED ou ARCHIVED. Sans valeur, tous

{
  "data": [
    { "id": "a86c727f-…", "name": "Dispositifs", "status": "ACTIVE", "marketId": "935b8a74-…", "activePrompts": 6 }
  ]
}

Créer un thème passe encore par le dashboard ou l'outil MCP create_topic.

---

GET /projects/:id/prompts

La bibliothèque de prompts, les plus anciens d'abord. Seuls les prompts ACTIVE partent dans un audit.

Paramètre	Défaut	Description
topicId	aucun	Un seul thème
status	aucun	ACTIVE, SUGGESTED, ARCHIVED ou DISMISSED
limit	100	De 1 à 500
offset	0	Le nextOffset de la page précédente

{
  "data": [
    {
      "id": "…",
      "prompt": "Qu'est-ce qu'Exemple Immo ?",
      "language": "fr",
      "marketId": "935b8a74-…",
      "topicId": "…",
      "status": "ACTIVE"
    }
  ],
  "nextOffset": null
}

nextOffset vaut null sur la dernière page.

---

POST /projects/:id/prompts

Crée des prompts dans un thème. Scope write requis.

{
  "topicId": "a86c727f-…",
  "prompts": [
    "Combien coûtent les frais de notaire dans le neuf ?",
    "Qui est éligible au PTZ en 2026 ?"
  ],
  "language": "fr"
}

Champ	Description
topicId	Obligatoire, un thème de la marque. Un appel par thème
prompts	De 1 à 50 textes par appel, de 10 à 1000 caractères, gardés tels quels, casse comprise
language	Facultatif. Par défaut, la langue du marché du thème

Les prompts créés sont actifs tout de suite et comptent dans le quota de prompts du forfait, 50 prompts actifs par marque sur le forfait payant. Une clé API n'a pas d'utilisateur : ils sont rattachés au propriétaire de l'organisation.

Réponse (201 Created) :

{
  "data": {
    "created": 2,
    "duplicates": 0,
    "quotaSkipped": 0,
    "failed": 0,
    "failedPrompts": [],
    "topicActivePrompts": 8,
    "projectActivePrompts": 37,
    "quotaRemaining": 13
  }
}

Un doublon d'un prompt existant n'est pas recréé et compte dans duplicates. quotaSkipped compte ceux qui ne tenaient plus dans le quota, failedPrompts nomme ceux à renvoyer.

Statut	Cas
400	topicId absent, texte trop court ou trop long, plus de 50 prompts, langue non prise en charge
403	Clé sans scope write, ou quota de prompts de la marque atteint
404	Marque ou thème introuvable
409	Création impossible pour l'instant (organisation sans propriétaire, bibliothèque de prompts en cours de migration), réessayez plus tard

---

POST /projects/:id/prompts/archive

Archive jusqu'à 100 prompts. Scope write requis. Ils sortent des prochains audits et du quota, leurs résultats passés restent.

{ "promptIds": ["…", "…"] }

Réponse (200 OK) : { "data": { "archived": 2 } }. Si un id n'appartient pas à la marque, rien n'est archivé et la réponse est 404.

---

Suggestions IA →