Prompts

Les questions que nous posons aux modèles d’IA à la fréquence de suivi configurée pour le compte, et les enregistrements produits à chaque exécution.

GET/dimensions/prompts

Liste les prompts d’un projet.

  • Paramètres : project_id (obligatoire), model (uniquement les prompts ayant au moins une exécution sur ce modèle, quels qu’en soient le résultat et la date), collection_id, prompt (ID du prompt), country_code, language_code, from, to, page, per_page (≤100). from et to filtrent tous deux sur la date de création du prompt.

GET/dimensions/prompt_executions

Liste les exécutions de prompts d’un projet.

Paramètres :
  • project_idobligatoire
  • model
  • collection_id
  • promptID du prompt
  • country_code
  • language_code
  • prompt_type
  • brand_kind
  • from
  • to
  • page
  • per_page
  • mention_filter
  • citation_filter
  • competitorsla matrice à deux axes décrite pour GET /answers

GET/dimensions/query_fan_outs

Renvoie les sous-requêtes réellement émises par un modèle pour répondre à vos prompts suivis. Utile pour repérer les formulations que les modèles recherchent, plutôt que celles que vous avez rédigées. view=query (par défaut) renvoie une ligne par sous-requête distincte, avec son nombre d’occurrences et sa part du total des occurrences ; view=prompt renvoie une ligne par prompt, avec le nombre de sous-requêtes distinctes qu’il a produites. Ces sous-requêtes sont surtout fournies par ChatGPT : un résultat vide signifie généralement que les modèles concernés ne les exposent pas.

Paramètres :
  • project_idobligatoire
  • viewquery ou prompt
  • querysous-chaîne recherchée dans le texte de la sous-requête
  • order
  • direction
  • model
  • collection_id
  • prompt
  • country_code
  • language_code
  • prompt_type
  • brand_kind
  • range
  • from
  • to
  • page
  • per_page
  • output

GET/suggested_prompts

La file Prompts suggérés, la même liste que l’onglet Prompts suggérés de l’application : les suggestions de tous les générateurs, des plus anciennes aux plus récentes, en attente par défaut.

Paramètres :
  • project_idobligatoire
  • sourcewebsite, magic, topic, reddit, paa, reputational, translate, gsc ou catalog
  • statuspending, accepted, rejected ou all
  • page
  • per_page≤100, 50 par défaut

GET/prompt_generations/:id

Interrogez régulièrement une exécution de suggestions jusqu’à ce que son statut soit completed (avec les suggestions enregistrées) ou failed (avec un code et un message d’erreur). La plupart des exécutions se terminent en moins d’une minute. Les exécutions sont conservées 24 heures ; leurs suggestions restent dans la file.

Paramètres :
  • project_idobligatoire
  • :idID de l’exécution, dans l’URL

POST/prompts

Crée jusqu’à 100 prompts par requête. Les prompts existants (même texte, même pays et même langue) sont ignorés.

Corps (JSON) :
  • project_idobligatoire
  • promptstableau, obligatoire, 100 au maximum
  • country_codeobligatoire
  • language_codeobligatoire

POST/prompts/import

L’import CSV de l’application, au format JSON. Chaque ligne porte son propre pays, sa langue et ses tags. Les tags manquants sont créés, et les doublons sont ignorés mais reçoivent quand même les tags de la ligne ; si les nouveaux prompts dépassent la limite du forfait, rien n’est importé. Une ligne est ignorée et renvoyée dans row_errors quand son pays ou sa langue est inconnu, quand elle donnerait plus de 50 tags à un prompt (les lignes qui répètent un prompt s’additionnent) ou quand ses tags porteraient la requête au-delà de 500 nouveaux tags. Un membre de l’équipe a besoin de l’autorisation de création sur les tags pour créer un tag (sans elle, une ligne qui nécessite un nouveau tag est ignorée et renvoyée dans row_errors) et de l’autorisation de modification sur les prompts pour ajouter des tags à un prompt qui existait déjà (sans elle, la ligne n’ajoute aucun tag à ce prompt et est renvoyée dans row_errors lorsqu’elle en aurait ajouté un). Nécessite une clé API avec droit d’écriture et, pour les membres de l’équipe, l’autorisation de création sur les prompts.

  • Corps (JSON) : project_id (obligatoire), rows (tableau obligatoire, 500 lignes au maximum), chacune avec prompt (obligatoire), country_code, language_code (codes ou noms, ceux du projet par défaut) et tags (tableau de noms).

POST/prompt_generations

Lance une exécution de suggestions de prompts avec l’un des générateurs des assistants « Ajouter des prompts » de l’application. La requête répond 202 et l’exécution se poursuit en arrière-plan ; ses suggestions arrivent dans la file Prompts suggérés, et rien n’est suivi tant que vous ne les avez pas acceptées. Nécessite une clé API avec droit d’écriture.

  • Corps (JSON) : project_id (obligatoire), source (obligatoire : website, keyword, topic, reddit, paa, reputational, translate ou search_console), country_code et language_code (ceux du projet par défaut). Selon la source : query (facultatif pour keyword, obligatoire pour topic et reddit), count (keyword et topic, de 1 à 100, 20 par défaut), competitor_id (keyword), search_type (reddit : topic ou brand), keywords (paa, 5 au maximum), source_country_code et source_language_code (translate), min_words et all_countries (search_console, à partir du forfait Growth).

POST /suggested_prompts/accept + /reject

Accepte des suggestions en attente pour les suivre comme prompts, chacune dans son pays et sa langue et, si besoin, dans un tag, ou les refuse pour les retirer de la liste en attente. Si les nouveaux prompts dépassent la limite de prompts du forfait, rien n’est accepté (ERR_LIMIT_REACHED). Nécessite une clé API avec droit d’écriture.

Corps (JSON) :
  • project_idobligatoire
  • idstableau obligatoire, 100 au maximum

L’endpoint accept prend aussi un tag via tag_ids ou tag_names, ainsi que create_missing (booléen).

PATCH/prompts/:id

Définit à la main, pour un prompt, l’intention de recherche (prompt_type) et/ou la marque dans le prompt (brand_kind), exactement comme en modifiant ses badges sur la page du prompt. Le prompt est marqué comme catégorisé manuellement (categorization_source devient manual) : la catégorisation automatique ne le modifie donc plus, et la page du prompt permet de revenir à la catégorisation automatique. Indisponible depuis un portail en marque blanche (ERR_INTEGRATION_UNAVAILABLE). Nécessite une clé API avec accès en écriture et, pour les membres de l’équipe, l’autorisation de modification sur les prompts. Également disponible via l’outil MCP update_prompt_categorization.

Chemin :
  • :idID du prompt

Corps (JSON) : project_id (obligatoire), prompt_type (informational|navigational|commercial|transactional), brand_kind (brand|brand_other|non_brand) ; au moins l’un des deux. Tout autre champ, ou une valeur inconnue, renvoie ERR_INVALID_PARAM.

DELETE/prompts/:id

Supprime un prompt. Action irréversible : le prompt disparaît immédiatement, libère une place dans le quota de prompts, et son historique (exécutions, mentions, citations, sentiment) est purgé par une tâche en arrière-plan. Nécessite une clé API avec accès en écriture.

Paramètres :
  • project_idobligatoire
  • :iddans l’URL

Renvoie ERR_NOT_FOUND pour les prompts hors du projet.