> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/fr/developpeurs/tools.md).

# Outils

Référence des outils du serveur MCP d’AirOps : donnez à Claude, Cursor et à d’autres assistants IA un accès programmatique aux analyses AEO, aux Brand Kits, aux Grids, aux bases de connaissances, aux Playbooks et aux Workflows dans votre espace de travail AirOps

Le serveur MCP AirOps fournit aux assistants IA comme Claude et Cursor un accès programmatique, natif de l'IA, à votre espace de travail AirOps. Cette page répertorie les outils qu'il expose pour accéder à vos données et les gérer, organisés en plusieurs domaines : **AEO** (Answer Engine Optimization) pour l'analyse de la visibilité de l'IA, la configuration des prompts et les rapports, **Gestion de marque** pour gérer l'identité de marque, le style rédactionnel et les ressources visuelles, **Grilles** pour lire, écrire et créer des données Grid par programmation, **Bases de connaissances** pour la recherche sémantique et l'ingestion de documents, et **Playbooks et workflows** pour inspecter les définitions, examiner les retours et exécuter des travaux.

Les outils de liste et de récupération prennent en charge le filtrage, la sélection de champs, le tri et la pagination, le cas échéant. Les outils d'écriture documentent les champs requis dans chaque section.

## Accès au forfait

Les outils de ressources nécessitent un espace de travail payant. Les essais du niveau payant restent éligibles. Les espaces de travail gratuits peuvent se connecter, découvrir les outils et utiliser `list_workspaces`, mais les requêtes concernant leurs données renvoient une restriction liée au forfait. Si vous appartenez à la fois à des espaces de travail gratuits et payants, choisissez un espace de travail payant pour les requêtes et les modifications de ressources.

## Espace de travail et Brand Kit

### `list_workspaces`

Liste tous les espaces de travail auxquels vous avez accès.

**Renvoie :** ID de l'espace de travail, nom, identifiant et niveau d'abonnement.

| Paramètre   | Valeurs          |
| ----------- | ---------------- |
| **Filtres** | nom, niveau      |
| **Tri**     | nom, created\_at |

***

### `list_brand_kits`

Liste tous les Brand Kits auxquels vous avez accès. Renvoie `brand_management_enabled` et `aeo_enabled` des indicateurs pour chaque Brand Kit, afin que vous sachiez quelles fonctionnalités sont disponibles.

* Utiliser `get_brand_kit` pour les Brand Kits avec `brand_management_enabled: true`
* Utiliser `get_insights_settings` pour les Brand Kits avec `aeo_enabled: true`

**Renvoie :** ID du Brand Kit, nom, description, URL, nom de l'espace de travail, `brand_management_enabled`, et `aeo_enabled`.

| Paramètre   | Valeurs                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| **Filtres** | workspace\_name, brand\_name, brand\_url, brand\_management\_enabled, aeo\_enabled |
| **Tri**     | brand\_name, created\_at                                                           |

***

### `get_brand_kit`

Obtenez un Brand Kit spécifique par ID pour la gestion de marque et la création de contenu. Renvoie l'identité de marque, le style rédactionnel et les entités associées.

**Nécessite :** `id`

**Renvoie :** Nom de la marque, URL, description, persona rédactionnelle, ton rédactionnel, statut et horodatages. Inclut éventuellement des entités associées avec des données imbriquées.

| Paramètre  | Valeurs                                                                                                                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Inclut** | product\_lines, product\_lines.competitors, audiences, audiences.writing\_rules, content\_types, content\_types.content\_samples, content\_types.writing\_rules, regions, regions.writing\_rules, writing\_rules, custom\_variables |

***

### `get_insights_settings`

Obtenez la configuration des insights AEO pour un Brand Kit. Renvoie les informations nécessaires pour utiliser les outils AEO et d'analyse.

**Nécessite :** `id`

**Renvoie :** ID du Brand Kit, nom, URL, pays, statut AEO, nombre de prompts, description client, concurrents avec les URL de domaine et personas.

***

### `update_brand_kit`

Mettez à jour les champs de base d'un Brand Kit. Seuls les champs fournis sont modifiés.

**Nécessite :** `brand_kit_id`

**Champs modifiables :** `nom_de_marque`, `brand_url`, `brand_about`, `writing_persona`, `writing_tone`

***

### `list_topics`

Liste les sujets configurés pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID du sujet, nom et couleur.

| Paramètre   | Valeurs          |
| ----------- | ---------------- |
| **Filtres** | name             |
| **Tri**     | nom, created\_at |

***

### `create_topic`

Créez un nouveau sujet pour un Brand Kit. Les sujets regroupent les prompts suivis et les vues analytiques par thème.

**Nécessite :** `brand_kit_id`, `name`

**Champs facultatifs :** `couleur`

***

### `update_topic`

Mettez à jour le nom ou la couleur d'un sujet. Les affectations de prompts existantes restent rattachées au sujet.

**Nécessite :** `brand_kit_id`, `topic_id`

**Champs :** `name`, `couleur`

***

### `delete_topic`

Supprimez un sujet d'un Brand Kit.

**Nécessite :** `brand_kit_id`, `topic_id`

{% hint style="warning" %}
La suppression d'un sujet peut affecter l'organisation des prompts et les vues de rapports. Confirmez le sujet et l'impact en aval avant d'appeler cet outil.
{% endhint %}

***

### `list_personas`

Liste les personas configurés pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID du persona, titre et description.

| Paramètre   | Valeurs            |
| ----------- | ------------------ |
| **Filtres** | titre              |
| **Tri**     | titre, created\_at |

***

### `publish_brand_kit`

Publiez le brouillon actuel d'un Brand Kit afin que les modifications deviennent actives. Toutes les modifications effectuées via `update_brand_kit` et `manage_brand_kit_*` sont appliquées à un brouillon. La publication promeut le brouillon en version active et en crée un nouveau à partir de celui-ci.

**Nécessite :** `brand_kit_id`

{% hint style="warning" %}
Confirmez toujours avec l'utilisateur avant de publier. Cela rendra toutes les modifications en attente actives.
{% endhint %}

***

### `create_brand_kit_recap_entry`

Enregistrez une entrée de récapitulatif résumant les modifications apportées au Brand Kit pendant une session MCP. Utilisez cet outil une fois, vers la fin d'une session qui a modifié le Brand Kit, avec des preuves telles que des URL sources, des noms de pages ou de courtes citations dans `body_markdown`.

**Nécessite :** `brand_kit_id`, `titre`

**Champs facultatifs :** `body_markdown`

**Renvoie :** ID de l'entrée de récapitulatif, titre, source et message de succès.

***

## Gestion du Brand Kit

Outils pour créer et mettre à jour des entités Brand Kit. Chaque outil prend en charge à la fois la création (omettre `id`) et la mise à jour (fournir `id`) des opérations. Lors de la mise à jour, seuls les champs fournis sont modifiés.

{% hint style="info" %}
Les modifications sont enregistrées dans un **brouillon**. Utilisez `publish_brand_kit` pour les rendre actives.
{% endhint %}

### `manage_brand_kit_product_line`

Créez ou mettez à jour une gamme de produits pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `url`, `details`, `positioning`, `ideal_customer_profile`

***

### `manage_brand_kit_competitor`

Créez ou mettez à jour un concurrent pour un Brand Kit. Les concurrents doivent être associés à au moins une gamme de produits.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `domain`, `product_line_ids` (au moins un requis)

***

### `manage_brand_kit_audience`

Créez ou mettez à jour une audience pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `description`

***

### `manage_brand_kit_region`

Créez ou mettez à jour une région pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `description`, `icon_name` (icône drapeau, par ex. `flag-us`)

***

### `manage_brand_kit_content_type`

Créez ou mettez à jour un type de contenu pour un Brand Kit. À la création, vous pouvez fournir un `sample_url` pour amorcer le type de contenu. Le système extraira le contenu de l'URL et utilisera l'IA pour générer automatiquement les champs.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `template_outline`, `cta_text`, `cta_url`, `header_case` (title\_case, sentence\_case, custom), `header_case_custom_value`, `sample_url` (création uniquement)

***

### `manage_brand_kit_content_sample`

Créez ou mettez à jour un exemple de contenu pour un Brand Kit. À la création, l'URL de l'exemple est traitée de manière asynchrone pour en extraire le contenu.

**Nécessite :** `brand_kit_id`

**Champs :** `url` (requis à la création), `content_type_id` (requis à la création), `content` (mise à jour uniquement), `audience_ids`, `region_ids`

***

### `manage_brand_kit_writing_rule`

Créez ou mettez à jour une règle rédactionnelle pour un Brand Kit. Les règles peuvent être globales ou limitées à un seul type de contenu, une audience ou une région (mutuellement exclusifs). La portée est définie uniquement à la création.

**Nécessite :** `brand_kit_id`

**Champs :** `text` (requis à la création), `content_type_id` (création uniquement), `audience_id` (création uniquement), `region_id` (création uniquement)

***

### `manage_brand_kit_custom_variable`

Créez ou mettez à jour une variable personnalisée pour un Brand Kit. Les variables personnalisées sont déconseillées dans la plupart des cas d'utilisation. Préférez plutôt les régions, les audiences, les types de contenu ou les règles rédactionnelles.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `valeur` (requis à la création)

***

### `create_brand_kit_direct_upload`

Lancez un envoi direct pour les ressources visuelles du Brand Kit, telles que les logos, les exemples visuels et les fichiers de polices. L'outil renvoie une URL de dépôt pré-signée, les en-têtes d'envoi et un `signed_id` à transmettre à l'outil de gestion de la ressource visuelle concernée.

**Nécessite :** `brand_kit_id`, `nom_de_fichier`, `type_de_contenu`, `taille_en_octets`, `checksum`

**Renvoie :** `signed_id`, `upload_url`, et `upload_headers`.

***

### `manage_brand_kit_palette`

Créez ou mettez à jour une palette de couleurs pour un brouillon de Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création)

***

### `manage_brand_kit_palette_color`

Créez ou mettez à jour une couleur dans une palette de Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `palette_id` (requis à la création), `name` (requis à la création), `valeur` (requis à la création), `instructions_d_utilisation`

***

### `manage_brand_kit_logo_variant`

Créez ou mettez à jour une variante de logo pour un brouillon de Brand Kit. Joignez un fichier avec `signed_id` depuis `create_brand_kit_direct_upload` ou avec un `file_url`.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `background_color`, `instructions_d_utilisation`, `signed_id`, `file_url`

***

### `manage_brand_kit_logo_size`

Créez ou mettez à jour les dimensions recommandées du logo et les instructions d'utilisation.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `largeur`, `hauteur`, `instructions_d_utilisation`

***

### `manage_brand_kit_font`

Créez ou mettez à jour une police du Brand Kit. Joignez un fichier de police avec `signed_id` depuis `create_brand_kit_direct_upload` ou avec un `file_url`.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `instructions_d_utilisation`, `google_font_link`, `signed_id`, `file_url`

***

### `manage_brand_kit_type_size`

Créez ou mettez à jour une taille typographique associée à une police du Brand Kit.

**Nécessite :** `brand_kit_id`

**Champs :** `font_id`, `name` (requis à la création), `poids`, `taille`, `hauteur_de_ligne`, `instructions_d_utilisation`

***

### `manage_brand_kit_usage_rule`

Créez ou mettez à jour une règle d'utilisation du Brand Kit. `s'applique_à` est défini à la création et ne peut pas être modifié ultérieurement.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `s'applique_à` (requis à la création)

***

### `manage_brand_kit_visual_use_case`

Créez ou mettez à jour un cas d'utilisation visuel, un groupe nommé d'exemples visuels avec des instructions partagées.

**Nécessite :** `brand_kit_id`

**Champs :** `name` (requis à la création), `instructions`

***

### `manage_brand_kit_visual_example`

Créez ou mettez à jour un exemple visuel pour un Brand Kit. Les exemples visuels doivent être regroupés sous un cas d'utilisation visuel. Joignez une image avec `signed_id` depuis `create_brand_kit_direct_upload` ou avec un `file_url`.

**Nécessite :** `brand_kit_id`

**Champs :** `visual_use_case_id` (requis à la création), `titre` (requis à la création), `sample_url`, `instructions_d_utilisation`, `signed_id`, `file_url`

***

### Modifier un brouillon de Brand Kit <a href="#suggest_brand_kit_edits" id="suggest_brand_kit_edits"></a>

Utiliser `update_brand_kit` pour les champs de base et l' `manage_brand_kit_*` outil approprié pour les entités associées. Résumez les modifications prévues et obtenez la confirmation de l'utilisateur avant de les appliquer.

Ces outils écrivent directement dans le brouillon. Relisez le brouillon pour vérifier le résultat et indiquez à l'utilisateur que les modifications ne sont pas encore actives. Demandez une confirmation explicite avant d'appeler `publish_brand_kit`; la publication est une action distincte qui rend toutes les modifications en attente actives.

L'ancien `suggest_brand_kit_edits` l'outil d'examen interactif n'est plus disponible.

***

## Prompts et réponses AEO

### `list_aeo_prompts`

Liste les prompts IA suivis pour un Brand Kit.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID du prompt, texte, mot-clé, présence de la marque, volume, ID du sujet, horodatages, taux\_de\_mention, taux\_de\_citation et tendances.

| Paramètre           | Valeurs                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------ |
| **Filtres**         | text, strategy, brand\_mentioned, topic\_id, prompt\_volume, mention\_rate, citation\_rate |
| **Tri**             | text, created\_at, prompt\_volume, mention\_rate, citation\_rate                           |
| **Inclut**          | sujet, tags                                                                                |
| **Filtres de date** | start\_date, end\_date, providers, countries, personas                                     |

***

### `create_aeo_prompt`

Créez un nouveau prompt AEO suivi pour un Brand Kit. Des tâches en arrière-plan analysent le prompt, extraient les mots-clés et calculent les métriques de volume après la création.

**Nécessite :** `brand_kit_id`, `text`, `topic_id`

**Champs facultatifs :** `countries`, `persona_ids`, `platforms`

{% hint style="warning" %}
La création de prompts peut affecter le volume de réponses. Confirmez le texte du prompt, le sujet et les affectations avec l'utilisateur avant d'appeler cet outil.
{% endhint %}

***

### `get_prompt_answers`

Obtenez les réponses IA pour un prompt spécifique.

**Nécessite :** `prompt_id`

**Renvoie :** ID de la réponse, texte (tronqué), fournisseur, pays, marque mentionnée, marque citée, horodatages, et le `intent_stage` (`awareness`, `consideration`, `evaluation`, `purchase`, ou `null`).

| Paramètre   | Valeurs        |
| ----------- | -------------- |
| **Filtres** | pays, personas |
| **Tri**     | created\_at    |
| **Inclut**  | persona        |

***

### `get_answer`

Obtenez une réponse IA spécifique par ID avec le texte complet.

**Nécessite :** `id`

**Renvoie :** Texte complet de la réponse (non tronqué), fournisseur, pays, marque mentionnée, marque citée, `intent_stage`, et éventuellement les citations, mentions et détails du persona.

| Paramètre  | Valeurs                      |
| ---------- | ---------------------------- |
| **Inclut** | citations, mentions, persona |

Utilisez ceci après `get_prompt_answers` pour récupérer le texte complet de la réponse avec les URL et positions des citations.

***

### `list_answers`

Liste les réponses IA dans un Brand Kit avec des filtres pour la plage de dates, les fournisseurs, les pays, les personas et d'autres dimensions AEO. Utilisez ceci lorsque vous avez besoin de réponses sur de nombreux prompts plutôt que de réponses pour un seul prompt.

**Nécessite :** `brand_kit_id`

Chaque réponse inclut le `intent_stage`, ou `null` du prompt lorsque la classification n'est pas disponible.

***

## Configuration AEO et gestion des prompts

### `create_aeo_persona`

Créez un nouveau persona AEO pour un Brand Kit. Les personas représentent les points de vue utilisateur utilisés pour simuler des requêtes de recherche IA.

**Nécessite :** `brand_kit_id`, `titre`, `description`

**Champs facultatifs :** `add_to_all_prompts`

***

### `add_aeo_region`

Ajoutez un code pays ISO alpha-2 aux régions AEO configurées d'un Brand Kit.

**Nécessite :** `brand_kit_id`, `country_code`

**Champs facultatifs :** `add_to_all_prompts`

***

### `list_tags`

Liste les tags AEO configurés pour un Brand Kit.

**Nécessite :** `brand_kit_id`

| Paramètre   | Valeurs          |
| ----------- | ---------------- |
| **Filtres** | name             |
| **Tri**     | nom, created\_at |

***

### `create_aeo_tag`

Créez un nouveau tag AEO sur un Brand Kit. Les tags sont des étiquettes définies par l'utilisateur qui peuvent être appliquées aux prompts.

**Nécessite :** `brand_kit_id`, `name`

**Champs facultatifs :** `couleur`

***

### `update_aeo_tag`

Mettez à jour le nom ou la couleur d'un tag AEO. Les affectations de tags existantes sont conservées.

**Nécessite :** `brand_kit_id`, `tag_id`

**Champs :** `name`, `couleur`

***

### `delete_aeo_tag`

Supprimez un tag AEO d'un Brand Kit et retirez-le de chaque prompt qui l'utilise.

**Nécessite :** `brand_kit_id`, `tag_id`

{% hint style="warning" %}
Cette action supprime définitivement le tag et retire ses affectations de tags aux prompts. Confirmez le tag et son impact avant de l'appeler.
{% endhint %}

***

### `bulk_update_aeo_prompt_tags`

Ajoutez ou supprimez un ou plusieurs tags sur un lot de prompts AEO en une seule transaction.

**Nécessite :** `brand_kit_id`, `prompt_ids`, `operation`, `tag_ids`

**Opérations :** `ajouter`, `supprimer`

***

### `update_aeo_prompt_assignments`

Préparez des modifications d'affectation de brouillon pour un ou plusieurs prompts AEO. Les affectations incluent les pays, les personas et les plateformes. Les modifications ne deviennent actives qu'une fois `commit_aeo_prompt_assignments` exécuté.

**Nécessite :** `brand_kit_id`, `prompts`

**Champs du prompt :** `prompt_id`, `countries`, `persona_ids`, `platforms`

***

### `get_aeo_prompt_assignments_status`

Inspectez l'état actuel du brouillon d'affectations de prompts pour un Brand Kit. Utilisez ceci pour vérifier si un brouillon existe, s'il a des modifications et si son engagement dépasserait la limite de réponses de l'espace de travail.

**Nécessite :** `brand_kit_id`

***

### `commit_aeo_prompt_assignments`

Validez le brouillon actuel d'affectations de prompts pour le rendre actif. Cela remplace les affectations de pays, de personas et de plateformes actives par l'état du brouillon.

**Nécessite :** `brand_kit_id`

{% hint style="warning" %}
Cela affecte les affectations actives de suivi AEO. Confirmez avec l'utilisateur avant de valider.
{% endhint %}

***

### `discard_aeo_prompt_assignments`

Abandonnez le brouillon actuel d'affectations de prompts et créez un nouveau brouillon à partir des affectations actives.

**Nécessite :** `brand_kit_id`

{% hint style="warning" %}
Cela supprime toutes les modifications d'affectation en attente dans le brouillon partagé, y compris les modifications non enregistrées de l'interface. Confirmez avec l'utilisateur avant de l'appeler.
{% endhint %}

***

## Citations et domaines

Utiliser `prompt_type` avec l'opérateur `EQUALS` et la valeur `brand` ou `category` pour filtrer selon que le prompt mentionne le nom de votre marque. Utilisez `brand_mentioned` avec l'opérateur `EQ` et la valeur `true` ou `false` pour filtrer selon que la page citante mentionne votre marque.

L'ancien `brand_mentioned EQUALS brand/category` et `brand_referenced EQ true/false` les filtres restent acceptés comme alias de compatibilité. Préférez les noms explicites ci-dessus ; ils sont prioritaires lorsque les anciens et les nouveaux filtres sont fournis. Le `brand_mentioned` filtre sur `list_aeo_prompts` se réfère toujours au texte du prompt.

### `list_aeo_citations`

Liste les citations (URL) avec leurs métriques pour un Brand Kit. Affiche les URL individuelles citées dans les réponses IA.

**Nécessite :** `brand_kit_id`

**Renvoie :** URL, nom de domaine, catégorie de domaine, nombre de citations, part de citations, taux de citation, score d'influence, type de page, sentiment de marque, tendances et métadonnées sociales lorsque disponibles.

La `social` l'objet identifie la plateforme et contient `content` et `account` des enveloppes avec les métadonnées, les métriques et l'état de synchronisation. Il `null` lorsqu'aucun enregistrement social pris en charge n'existe. Le compte peut être `null` lorsqu'un contenu existe sans compte associé. Une collecte en attente ou échouée peut laisser les métadonnées incomplètes.

Les métadonnées du contenu YouTube incluent `duration_seconds`, `format`, et `sponsorship_status`. La durée peut être `null`; le format et l'état de sponsoring utilisent `unknown` lorsqu'elles ne sont pas disponibles.

| Paramètre           | Valeurs                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Filtres**         | domain\_category, domain\_id, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment, mentioned\_competitor\_domains |
| **Tri**             | citation\_count, citation\_share, citation\_rate, influence\_score                                                                    |
| **Filtres de date** | start\_date, end\_date, providers, countries, personas                                                                                |

**Catégories de domaine :** Owned, Competitors, Social, Communities, Reviews, Media, Educational, Marketplaces, Products, Affiliates, Other

***

### `get_aeo_citation`

Obtenez les détails et les prompts citant une URL spécifique.

**Nécessite :** `brand_kit_id`, `id` (l'ID de citation/URL)

**Renvoie :** Détails de l'URL, métriques de citation, répartition du score d'influence, type de page, sentiment de marque, concurrents mentionnés et la même `social` enveloppe renvoyée par `list_aeo_citations`.

***

### `list_aeo_domains`

Liste les domaines cités dans les réponses IA pour un Brand Kit. Agrégé par domaine avec des métriques de citation.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID du domaine, nom, catégorie, URL du logo, nombre de citations, nombre d'URL, part de citations, taux de citation et tendances.

| Paramètre           | Valeurs                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Filtres**         | domain\_category, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment |
| **Tri**             | citation\_count, citation\_share, citation\_rate                                          |
| **Filtres de date** | start\_date, end\_date, providers, countries, personas                                    |

***

## Ads et annonceurs observés par AEO

Annonces qu'AirOps observe dans les réponses ChatGPT et Google AI Mode pour vos prompts suivis. Ces outils interrogent les données d'annonces observées utilisées par [Annonces](/docs/fr/insights/ads.md), y compris **Bibliothèque d'annonces**, ils n'ont donc besoin d'aucune connexion de compte ChatGPT Ads.

{% hint style="info" %}
La couverture est limitée aux annonces qu'AirOps a vues dans sa propre collecte de réponses. Ces chiffres ne décrivent pas la couverture totale du marché, l'intention de ciblage, la diffusion des impressions ou les dépenses de l'annonceur.
{% endhint %}

### `list_aeo_ads`

Liste les annonces observées dans les réponses ChatGPT et Google AI Mode pour un Brand Kit. Chaque ligne représente une plateforme et une paire de créations observées. La même création sur deux plateformes produit deux lignes, chacune avec ses propres compteurs d'activité.

**Nécessite :** `brand_kit_id`

**Renvoie :** Fournisseur, ID de création observée, ID de famille observée, nom de l'annonceur, domaine, type et logo, titre et corps de l'annonce, apparitions, réponses, prompts, fréquence, first\_seen, last\_seen et days\_active.

| Paramètre           | Valeurs                                                      |
| ------------------- | ------------------------------------------------------------ |
| **Filtres**         | topic\_id, prompt\_id, prompt\_type                          |
| **Filtres de date** | start\_date, end\_date, providers, countries, personas, tags |

**Types d'annonceur :** owned, competitor, other

`list_aeo_ads` inclut par défaut les deux fournisseurs pris en charge. Passez `providers: ["chat_gpt"]` ou `providers: ["google_ai_mode"]` pour restreindre le périmètre. Utilisez `prompt_type EQUALS brand/category` pour la classification des prompts ; l'ancien `brand_mentioned` filtre de type de prompt reste un alias de compatibilité.

***

### `get_aeo_ad`

Obtenez une annonce observée, y compris son image créative et son URL de destination.

**Nécessite :** `brand_kit_id`, `id` (le `observed_creative_id` renvoyé par `list_aeo_ads`)

**Renvoie :** Fournisseur, ID de création observée, ID de famille observée, nom de l'annonceur, domaine, type et logo, titre de l'annonce, corps, image\_url, target\_url, first\_seen, last\_seen et days\_active.

Passez le fournisseur de la ligne sous la forme d'un `providers` un tableau ainsi que son ID créatif, par exemple `providers: ["google_ai_mode"]`. Les requêtes de détail utilisent par défaut ChatGPT lorsqu'aucun fournisseur n'est spécifié et nécessitent un seul fournisseur lorsqu'un fournisseur est fourni.

Les métriques sur fenêtre rapportées par `list_aeo_ads` (apparitions, réponses, requêtes, fréquence) ne sont pas renvoyées ici.

***

### `list_aeo_advertisers`

Liste les annonceurs observés dans les réponses de ChatGPT et du mode IA de Google pour un Brand Kit. Chaque annonce observée est rattachée à l'annonceur qui l'a diffusée, identifié par son domaine canonique.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID de l'annonceur, nom, domaine, type, URL du logo, nombre unique d'annonces, apparitions, réponses, requêtes, first\_seen et last\_seen.

| Paramètre           | Valeurs                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| **Filtres**         | topic\_id, prompt\_id, prompt\_type                                                               |
| **Tri**             | advertiser\_name, advertiser\_domain, ads, appearances, answers, prompts, first\_seen, last\_seen |
| **Filtres de date** | start\_date, end\_date, providers, countries, personas, tags                                      |

Les résultats sont triés par nombre unique d'annonces, les plus prolifiques d'abord, sauf si vous passez **Tri**. Utilisez `list_aeo_ads` pour les annonces individuelles derrière les comptes de chaque annonceur.

***

## Playbooks et retours

Lisez les définitions des Playbooks, consultez les sorties des sessions et les commentaires des évaluateurs, et exécutez ou publiez des Playbooks avec les autorisations de votre workspace existantes. La publication et l'exécution nécessitent une authentification OAuth utilisateur. Les exécutions peuvent consommer des crédits du workspace et effectuer les actions configurées dans le Playbook.

### `list_playbooks`

Liste les Playbooks modifiables, y compris les métadonnées du brouillon et de la version active.

**Nécessite :** `workspace_id`

**Facultatif :** `search` (titre), `page` (par défaut 1), `per_page` (par défaut 20, maximum 50).

### `get_playbook`

Lisez la configuration et la définition d'un Playbook en Markdown. Les références d'intégration n'exposent pas les identifiants.

**Nécessite :** `playbook_id`

**Facultatif :** `version_number`. Omettez-le pour lire le brouillon actuel (**Dernière**); indiquez un numéro pour lire une version publiée immuable.

### `list_playbook_sessions`

Liste les sessions dans l'ordre chronologique inverse.

**Nécessite :** `workspace_id`

**Facultatif :** `playbook_id`, `status`, `search` (nom de la session ou du créateur), `page` (par défaut 1), `per_page` (par défaut 20, maximum 50). Les sessions archivées utilisent le statut public `archivé`.

### `get_playbook_session`

Inspectez les métadonnées d'une session et une page d'événements, y compris le texte, les résultats d'outils, les artefacts et l'état d'achèvement.

**Nécessite :** `session_id`

**Facultatif :** `after_id` (curseur d'événement), `limit` (par défaut 20, maximum 50).

Passez le `next_after_id` en tant que `after_id` renvoyé pour continuer jusqu'à ce qu'il soit `null`. Les aperçus de texte sont limités à 2 000 caractères ; `content_truncated: true` indique que davantage de texte existe. Utilisez `read_playbook_output` pour la sortie complète.

### `read_playbook_output`

Lisez une sortie texte dans des pages basées sur les caractères. Les artefacts textuels collaboratifs reflètent le contenu actuel de l'éditeur, y compris les modifications apportées après l'exécution. Les artefacts binaires ne sont pas pris en charge.

**Nécessite :** `session_id` et exactement l'un de `event_id` ou `artifact_path`. Les chemins d'artefact doivent identifier un fichier sous `artifacts/external/`.

**Facultatif :** `offset` (par défaut 0), `max_chars` (par défaut 20 000, maximum 200 000).

**Renvoie :** `content`, `offset`, `total_chars`, et `next_offset`. Passez `next_offset` en retour comme `offset` jusqu'à ce qu'il soit `null`.

### `list_artifact_comments`

Lisez les commentaires des évaluateurs avec l'auteur, les horodatages, l'état de résolution et le contexte disponible autour de l'ancre ou du texte environnant.

**Nécessite :** `session_id`

**Facultatif :** `artifact_path` pour limiter les résultats à un seul artefact.

Utilisez les commentaires avec `read_playbook_output` pour examiner les retours en contexte. Les suggestions de suivi des modifications sont comptées séparément dans `suggestions_count`; elles ne sont pas des fils de commentaires. Cet outil lit les retours sans les modifier.

### `publish_playbook`

Publiez le brouillon actuel comme nouvelle version active.

**Nécessite :** `playbook_id` et l'authentification OAuth utilisateur.

**Facultatif :** `notes` pour la version publiée.

**Renvoie :** L'ID de la version active et les métadonnées de version. Confirmez le brouillon et l'intention de publication avant d'appeler cet outil ; la publication rend le brouillon en attente actif.

### `run_playbook`

Démarrez une session asynchrone. Chaque appel lance une nouvelle exécution.

**Nécessite :** `playbook_id` et l'authentification OAuth utilisateur.

**Facultatif :** `inputs` associés au nom de l'entrée, `message`, et `version_number`.

Par défaut, cela exécute le brouillon actuel (**Dernière**). Passez `version_number` pour exécuter une version publiée spécifique. L'exécution d'un brouillon ne le publie pas. Confirmez la version, les entrées et l'exécution prévues avant de démarrer.

**Renvoie :** `session_id`, `session_uuid`, le statut et les informations de version. Interrogez `get_playbook_session`, puis lisez les sorties et les commentaires selon les besoins.

## Workflows

Listez les workflows exécutables et démarrez ou inspectez les exécutions avec les autorisations de votre workspace. Les exécutions peuvent consommer des crédits et effectuer les actions configurées du workflow.

### `list_workflows`

Liste les workflows publiés que vous pouvez exécuter. Les ressources réservées aux brouillons, supprimées, d'agent et héritées sont exclues.

**Nécessite :** `workspace_id`

**Facultatif :** `search`, `page` (par défaut 1), `per_page` (par défaut 20, maximum 50).

### `run_workflow`

Démarrez une exécution asynchrone. Chaque appel lance une nouvelle exécution.

**Nécessite :** `workflow_id`

**Facultatif :** `inputs` associés au nom de l'entrée et `version_number`.

La valeur par défaut est la version publiée active. Passez `version_number` pour sélectionner une autre version publiée. Confirmez le workflow, les entrées et l'exécution prévus avant de démarrer.

**Renvoie :** `execution_id`, le statut et les informations de workflow/version.

### `get_workflow_execution`

Inspectez le statut, la sortie ou l'erreur d'une exécution.

**Nécessite :** `execution_id` renvoyé par `run_workflow`.

Interrogez cet outil pour suivre l'exécution à travers des états tels que `pending`, `en cours d'exécution`, `révision requise`, `succès`, `error`, ou `annulé`. Un ID d'exécution renvoyé signifie que l'exécution a démarré ; vérifiez son statut avant de considérer sa sortie comme complète.

## Exemple : examiner une exécution de Playbook

1. Trouvez le Playbook avec `list_playbooks` et inspectez sa définition avec `get_playbook`.
2. Trouvez une session avec `list_playbook_sessions`, puis lisez ses événements avec `get_playbook_session`.
3. Lisez le texte complet avec `read_playbook_output` et les retours des évaluateurs avec `list_artifact_comments`.
4. Résumez la sortie et les retours non résolus pour l'évaluateur.

## Analyse des pages

### `list_pages`

Liste les pages avec les métriques AEO, Google Search Console et GA4.

**Nécessite :** `brand_kit_id`

**Renvoie :** Pour chaque page : URL, chemin du dossier, mot-clé principal et métriques :

* **AEO :** citations\_count, citation\_rate, prompts\_count et tendances
* **GSC :** clics, impressions, ctr, position et tendances
* **GA4 :** trafic, sessions, engagement, average\_session\_engagement et tendances
* **Analyse de l'agent :** `user_browse` (Visites de l'agent IA), `ai_training` (Explorations d'entraînement), et `ai_search` (Crawls de recherche Web)

L'Analyse de l'agent doit d'abord être connectée. Ses trois compteurs prennent en charge le filtrage et le tri pour les dates sélectionnées, sans variantes de changement. Utilisez `list_aeo_agent_analytics` pour les Total Crawls et les répartitions quotidiennes.

| Paramètre                | Valeurs                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Filtres**              | Tout champ de métrique, url, folder\_name, primary\_keyword, session\_source, session\_medium          |
| **Tri**                  | Tous les champs de métrique, url, folder\_name                                                         |
| **Filtres intelligents** | almost\_page\_one, losing\_clicks, rankings\_slipping, losing\_ai\_visibility, citation\_rate\_decline |

**Filtres intelligents** (à utiliser à la place d'un filtrage manuel) :

| Filtre                  | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `almost_page_one`       | Pages classées #11-20 (gains rapides pour la page 1) |
| `losing_clicks`         | Baisse des clics avec position stable                |
| `rankings_slipping`     | Position en baisse au fil du temps                   |
| `losing_ai_visibility`  | Perte de citations AEO                               |
| `citation_rate_decline` | Perte d'autorité IA avec SEO stable                  |

***

### `create_page`

Ajoutez une page aux pages AEO d'un Brand Kit. AirOps normalise l'URL, vérifie qu'elle appartient au domaine AEO configuré du Brand Kit et exige qu'elle soit unique au sein de ce Brand Kit.

**Nécessite :** `brand_kit_id`, `url`

**Renvoie :** ID de page, ID du Brand Kit, ID du domaine AEO, URL normalisée, statut suivi, horodatage de création et message de confirmation.

Confirmez l'URL et le Brand Kit avec l'utilisateur avant de créer la page. Vérifiez le résultat avec `list_pages` filtré par URL. Cela ajoute la page à AirOps ; cela ne publie pas de contenu dans un CMS.

***

### `get_page_details`

Obtenez les métriques détaillées pour une page spécifique.

**Nécessite :** `id`

**Renvoie :** URL, dossier, mot-clé principal, part de citations, taux de citation, nombre unique de questions citées, métriques GSC (clics, impressions, position, CTR) et toutes les tendances.

| Paramètre          | Valeurs                |
| ------------------ | ---------------------- |
| **Plage de dates** | start\_date, end\_date |

***

### `get_page_prompts`

Obtenez les prompts IA qui citent une page spécifique.

**Nécessite :** `brand_kit_id`, `web_page_id`

**Renvoie :** ID du prompt, texte, mot-clé, topic\_id, volume, total\_answers, answers\_with\_citations, citation\_rate, mention\_rate et tendances.

| Paramètre          | Valeurs                                    |
| ------------------ | ------------------------------------------ |
| **Filtres**        | providers, countries, personas, topic\_ids |
| **Inclut**         | topic                                      |
| **Plage de dates** | start\_date, end\_date                     |

***

## Agent Analytics

### `list_aeo_agent_analytics`

Liste les requêtes quotidiennes du bot vers les pages suivies du Brand Kit. [Connecter l'analyse de l'agent](/docs/fr/insights/onsite/traffic.md) avant d'interroger ces données.

**Nécessite :** `brand_kit_id`

**Renvoie :** Lignes contenant `date`, `platform`, `crawl_type`, et `count`. Les types de crawl sont `ai_search`, `ai_training`, `user_browse`, et `autres`. Les lignes sans requêtes sont omises.

| Paramètre          | Valeurs                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| **Plage de dates** | `start_date`, `end_date`                                               |
| **Filtres**        | `platform`, `crawl_type`, ou un seul `web_page_id` depuis `list_pages` |
| **Tri**            | `date` (par défaut), `count`, ou `-count`                              |
| **Pagination**     | `page`, `per_page` (25 par défaut, 100 maximum)                        |

Lisez chaque page avant de sommer les comptes. L'analyse de l'agent **Nombre total de crawls** compte récapitule les crawls de recherche et d'entraînement pour les moteurs IA suivis. Le **Pages** Total Crawls du tableau compte chaque plateforme et type de crawl pour cette page. Utilisez le [guide de calcul de l'API](/docs/fr/developpeurs/api.md#agent-analytics) pour l'ensemble exact de moteurs, les recettes de graphiques et le comportement aux bornes de dates.

## Analytique

### `query_analytics`

Analysez les requêtes avec des métriques, dimensions et filtres flexibles. Interface de style BI pour une analyse personnalisée.

**Nécessite :** `brand_kit_id`, `métriques`

**Renvoie :** Résultats de la requête avec les métriques demandées regroupées par dimensions, plus les métadonnées.

**Métriques :**

| Métrique             | Description                                            |
| -------------------- | ------------------------------------------------------ |
| `taux_de_mention`    | % des réponses mentionnant la marque (0-100)           |
| `share_of_voice`     | Mentions de la marque vs concurrents (0-100)           |
| `taux_de_citation`   | % des réponses citant le domaine de la marque (0-100)  |
| `citation_share`     | Citations de la marque vs toutes les citations (0-100) |
| `citation_count`     | Nombre absolu de citations                             |
| `sentiment_score`    | Sentiment moyen (0-100)                                |
| `average_position`   | Rang moyen dans les listes de réponses                 |
| `answer_count`       | Nombre total de réponses analysées                     |
| `first_mention_rate` | % où la marque est mentionnée en premier (0-100)       |

**Dimensions** (max 3) :

| Dimension         | Description                              |
| ----------------- | ---------------------------------------- |
| `date`            | Regrouper par période                    |
| `provider`        | Regrouper par fournisseur d'IA           |
| `topic`           | Regrouper par sujet suivi                |
| `competitor`      | Regrouper par concurrent                 |
| `country`         | Regrouper par région/pays                |
| `persona`         | Regrouper par persona client             |
| `domain`          | Regrouper par domaine cité               |
| `domain_category` | Regrouper par type de source de citation |

| Paramètre          | Valeurs                                                            |
| ------------------ | ------------------------------------------------------------------ |
| **granularité**    | quotidienne, hebdomadaire, mensuelle, totale (par défaut : totale) |
| **Plage de dates** | start\_date, end\_date (par défaut : 7 derniers jours)             |
| **Filtres**        | providers, topics, countries, personas, brand\_mentioned           |
| **Limite**         | lignes max (par défaut 100, max 1000)                              |
| **order\_by**      | tri personnalisé (par ex. « citation\_count DESC »)                |

***

### `get_sentiment_theme_answers`

Obtenez les réponses derrière un thème de sentiment afin d'inspecter le texte source des réponses et les exemples pour ce thème.

**Nécessite :** `brand_kit_id`, `sentiment_theme_id`

**Champs facultatifs :** `start_date`, `end_date`, `providers`, `countries`, `topic_ids`, `persona_ids`, `page`, `per_page`

***

### `analytics_chart`

{% hint style="info" %}
**Application interactive :** Cet outil affiche un graphique dans la conversation. Disponible dans **Codex via le plugin AirOps, Claude Web et Claude Desktop**.
{% endhint %}

Analysez les requêtes et affichez-les sous forme de graphique interactif. Renvoie les données avec une référence d'interface pour la visualisation.

**Nécessite :** `brand_kit_id`, `métriques`

**Renvoie :** Données du graphique avec visualisation interactive rendue dans la conversation.

| Paramètre          | Valeurs                                                                              |
| ------------------ | ------------------------------------------------------------------------------------ |
| **chart\_type**    | line, bar, pie, area (par défaut : line)                                             |
| **métriques**      | Identique à query\_analytics                                                         |
| **dimensions**     | Identique à query\_analytics (max 2 pour les graphiques linéaires avec regroupement) |
| **granularité**    | quotidienne, hebdomadaire, mensuelle, totale                                         |
| **Plage de dates** | start\_date, end\_date                                                               |
| **Filtres**        | providers, topics, countries, personas, brand\_mentioned                             |
| **titre**          | Titre facultatif du graphique                                                        |

**Contraintes :**

* Seules les métriques de la même échelle peuvent être tracées ensemble (pourcentage, nombre ou position)
* Les graphiques en aires et en barres prennent en charge une seule métrique avec une seule dimension
* Les graphiques linéaires prennent en charge jusqu'à 2 dimensions, mais une seule métrique lorsqu'on en utilise 2

***

## Rapports

### `list_reports`

Liste les rapports analytiques enregistrés.

**Nécessite :** `brand_kit_id`

**Renvoie :** ID du rapport, nom, created\_at, updated\_at.

| Paramètre   | Valeurs                        |
| ----------- | ------------------------------ |
| **Filtres** | name                           |
| **Tri**     | name, created\_at, updated\_at |
| **Inclut**  | modules                        |

***

### `get_report`

Obtenez un rapport spécifique par ID.

**Nécessite :** `brand_kit_id`, `id`

**Renvoie :** ID du rapport, nom, horodatages. Avec `includes: ['modules']`, renvoie les configurations complètes des modules.

***

## Grilles

Outils pour lire, écrire, créer et exécuter des Grids AirOps par programmation. Utilisez-les pour remplir des données, gérer des colonnes, déclencher des exécutions de workflow et récupérer des résultats.

### `create_grid`

Créez une nouvelle Grid vierge et polyvalente avec une feuille vide. Utilisez `add_grid_column` pour ajouter des colonnes et `write_grid` pour ajouter des lignes.

**Nécessite :** `name`

**Champs facultatifs :** `workspace_id`

***

### `create_grid_sheet`

Créez une nouvelle feuille dans une Grid existante.

**Nécessite :** `grid_id`, `name`

***

### `list_grids`

Liste les grids auxquelles l'utilisateur authentifié a accès. Utilisez `includes: ["grid_tables.grid_columns"]` pour obtenir la structure des tables et des colonnes nécessaire aux autres outils de grid.

**Renvoie :** ID de Grid, nom, ID du workspace, et éventuellement détails des tables et colonnes (ID, titre, type de données, position).

| Paramètre   | Valeurs                        |
| ----------- | ------------------------------ |
| **Filtres** | name, workspace\_id            |
| **Tri**     | name, updated\_at, created\_at |
| **Inclut**  | grid\_tables.grid\_columns     |

***

### `read_grid`

Lisez les lignes d'une table de grid. Renvoie les lignes sous forme d'objets avec les titres de colonnes comme clés.

**Nécessite :** `grid_id`, `grid_table_id`

**Renvoie :** Métadonnées de la grid, colonnes (avec indicateur d'écriture autorisée) et données des lignes avec informations de pagination.

Les colonnes du Playbook incluent également `playbook_id` et `artifacts`, avec le `name` et `artifact_type`de chaque artefact. Utilisez ces noms lors du mappage de la sortie d'une colonne de Playbook vers une autre colonne d'exécution.

| Paramètre             | Tapez   | par défaut | Description                                                     |
| --------------------- | ------- | ---------- | --------------------------------------------------------------- |
| `filters`             | tableau | aucun      | Filtrer par valeurs de colonne                                  |
| `filters[].column_id` | entier  | aucun      | ID de colonne sur lequel filtrer                                |
| `filters[].operator`  | chaîne  | aucun      | CONTAINS, NOT\_CONTAINS, EMPTY, NOT\_EMPTY, =, !=, >=, <=, >, < |
| `filters[].value`     | chaîne  | aucun      | Valeur du filtre (non requise pour EMPTY/NOT\_EMPTY)            |
| `column_ids`          | tableau | tous       | ID des colonnes à inclure dans les résultats                    |
| `limit`               | entier  | 50         | Lignes par page (1–100)                                         |
| `offset`              | entier  | 0          | Décalage de ligne pour la pagination                            |
| `troncature`          | entier  | 0          | Caractères max par cellule (0 = pas de troncature)              |

***

### `read_grid_cell`

Lisez la valeur complète d'une cellule Grid unique. Utilisez cela lorsque `read_grid` tronque une cellule longue, comme un article complet, un brief, un payload JSON ou un champ HTML.

**Nécessite :** `grid_id`, `grid_table_id`, `row_id`, `column_id`

**Renvoie :** Titre de la colonne, valeur complète et type de valeur.

***

### `write_grid`

Créez ou mettez à jour des lignes dans une table de grid. 1000 lignes maximum par appel.

**Nécessite :** `grid_id`, `grid_table_id`, `mode`, `lignes`

| Paramètre | Tapez   | Description                                                                                                      |
| --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `mode`    | chaîne  | `create` pour ajouter de nouvelles lignes, `update` pour modifier des lignes existantes                          |
| `lignes`  | tableau | Objets de ligne avec les titres de colonnes comme clés. Pour `update` mode, incluez `__id` avec l'ID de la ligne |

**Renvoie :** `rows_created` (mode create) ou `rows_updated` et `cells_updated` (mode update).

{% hint style="info" %}
Les valeurs peuvent être des chaînes, des nombres, des booléens, des tableaux ou des objets. Les tableaux et les objets sont stockés en JSON. Les titres de colonnes doivent correspondre exactement aux colonnes de grid existantes. Utilisez `add_grid_column` pour créer d'abord de nouvelles colonnes.
{% endhint %}

***

### `run_grid_rows`

Déclenchez l'exécution d'une ou plusieurs lignes de grid. Cela exécute toutes les colonnes de workflow (exécution d'application) pour chaque ligne spécifiée, dans l'ordre des dépendances. L'exécution est asynchrone — cet outil renvoie immédiatement les métadonnées d'exécution.

**Nécessite :** `grid_id`, `grid_table_id`, `grid_row_ids`

| Paramètre      | Tapez   | Description                               |
| -------------- | ------- | ----------------------------------------- |
| `grid_row_ids` | tableau | ID des lignes de grid à exécuter (max 50) |

**Renvoie :** Métadonnées d'exécution, y compris les IDs d'exécution de lignes à interroger avec `get_grid_row_execution_status`.

{% hint style="info" %}
50 lignes maximum par appel. Utilisez `get_grid_row_execution_status` pour vérifier la progression et l'achèvement.
{% endhint %}

***

### `get_grid_row_execution_status`

Vérifiez le statut des exécutions des lignes Grid. Utilisez ceci après `run_grid_rows` pour interroger jusqu'à l'achèvement.

**Nécessite :** `grid_id`, `row_execution_ids`

| Paramètre           | Tapez   | Description                                               |
| ------------------- | ------- | --------------------------------------------------------- |
| `row_execution_ids` | tableau | Identifiants des exécutions de lignes à vérifier (50 max) |

**Renvoie :** Statut global et détails par colonne pour chaque exécution.

***

### `add_grid_column`

Ajoutez une nouvelle colonne à un tableau Grid. Utilisez ceci avant `write_grid` lorsque vous devez écrire dans une colonne qui n'existe pas encore.

**Nécessite :** `grid_id`, `grid_table_id`, `titre`, `data_type`

| Paramètre   | Tapez  | Description                                                                                                       |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `titre`     | chaîne | Titre de la colonne                                                                                               |
| `data_type` | chaîne | texte, nombre, datetime, markdown, url, html, image\_from\_url, json, sélection\_unique, playbook, app\_execution |
| `position`  | entier | Position de colonne facultative (ajoutée à la fin si omise)                                                       |

**Renvoie :** ID, titre, type de données et position de la colonne créée.

Pour une colonne Playbook, utilisez `data_type: "playbook"` et fournissez `playbook_id`. Pour une colonne Workflow, utilisez `data_type: "app_execution"` et fournissez `workflow_id`. Configurez `inputs` par nom d'entrée. Chaque mappage nécessite `type` et `valeur`.

Lors du mappage à partir d'une colonne Playbook, `valeur` est l'ID de la colonne source dans la même feuille, et `artifact_name` est le nom exact de l'artefact :

```json
{
  "article": {
    "type": "column",
    "value": 123,
    "artifact_name": "Final Article"
  }
}
```

Cet exemple est un `inputs` objet. Copiez le nom de l'artefact depuis `read_grid`, ou depuis les `artifacts` métadonnées renvoyées lorsque `add_grid_column` crée la colonne Playbook source.

***

### `update_grid_column`

Mettre à jour le titre, le type de données ou les mappages d'entrée Playbook/Workflow d'une colonne Grid.

**Nécessite :** `grid_id`, `grid_table_id`, `grid_column_id`, et au moins un de `titre`, `data_type`, ou `inputs`

**Renvoie :** Les ID du Grid et de la feuille ainsi que l'ID, le titre, le type de données et la position de la colonne mise à jour. Les colonnes Playbook et Workflow incluent également leurs détails de configuration.

Le passage de `inputs` remplace l'ensemble du mappage d'entrée. Incluez chaque entrée que vous souhaitez conserver. L'outil ne peut pas repositionner une colonne ni changer le Playbook ou le Workflow qu'elle exécute.

***

### `delete_grid_column`

Supprimez une colonne Grid et ses colonnes de sortie Workflow ou d'artefacts Playbook dépendantes.

**Nécessite :** `grid_id`, `grid_table_id`, `grid_column_id`

**Renvoie :** `grid_id`, `grid_table_id`, et `deleted_column_ids` pour toutes les colonnes concernées.

{% hint style="warning" %}
Examinez les colonnes dépendantes avant de supprimer. La suppression est bloquée pendant que des exécutions de lignes sont en cours pour la feuille.
{% endhint %}

***

### Exemple : workflow de données Grid

Un workflow programmatique typique utilisant les outils Grid :

1. **Découvrir :** Appelez `list_grids` avec des inclusions pour trouver le Grid et sa structure de colonnes
2. **Préparer :** Appelez `add_grid_column` pour créer les colonnes manquantes
3. **Remplir :** Appelez `write_grid` avec le mode `create` pour ajouter des lignes
4. **Exécuter :** Appelez `run_grid_rows` pour déclencher les colonnes de workflow de la ligne, puis interroger `get_grid_row_execution_status` jusqu'à achèvement
5. **Récupérer :** Appelez `read_grid` pour récupérer les résultats
6. **Mettre à jour :** Appelez éventuellement `write_grid` avec le mode `update` pour réécrire les données

***

## Bases de connaissances

### `list_knowledge_bases`

Listez toutes les bases de connaissances auxquelles vous avez accès. Les bases de connaissances stockent des documents pour la recherche sémantique.

**Renvoie :** ID de la base de connaissances, nom, ID de l'espace de travail, statut et nombre de documents. Seules les bases de connaissances dont le statut est `prêt` peuvent être recherchées.

| Paramètre   | Valeurs                              |
| ----------- | ------------------------------------ |
| **Filtres** | workspace\_name, name, workspace\_id |
| **Tri**     | nom, created\_at                     |

***

### `knowledge_base_manage`

Créez ou mettez à jour une base de connaissances. Omettez `knowledge_base_id` pour créer une nouvelle base de connaissances ; fournissez-le pour mettre à jour une base existante.

**Champs :** `knowledge_base_id`, `name`, `workspace_id`

**Requis à la création :** `name`, ainsi que `workspace_id` lorsque l'utilisateur a accès à plusieurs espaces de travail.

**Renvoie :** ID de la base de connaissances, nom, ID de l'espace de travail, statut, nombre de documents et indication de création.

***

### `search_knowledge_base`

Recherchez du contenu pertinent dans une base de connaissances à l'aide de la similarité sémantique.

**Nécessite :** `knowledge_base_id`, `query`

**Paramètres :** `top_k` (nombre de résultats, 1 à 20, 5 par défaut)

**Renvoie :** Contenu correspondant classé par pertinence.

***

### `knowledge_base_create_direct_upload`

Démarrez le flux de téléversement de fichier en deux étapes pour l'ingestion dans la base de connaissances. L'outil renvoie une URL de téléversement pré-signée, les en-têtes requis et un `signed_id`.

**Nécessite :** `knowledge_base_id`, `nom_de_fichier`, `type_de_contenu`, `taille_en_octets`, `checksum`

**Renvoie :** `signed_id`, `upload_url`, et `upload_headers`.

***

### `knowledge_base_add_file`

Enregistrez un fichier téléversé auprès d'une base de connaissances après `knowledge_base_create_direct_upload`. Le document est placé en file d'attente pour l'indexation.

**Nécessite :** `knowledge_base_id`, `signed_id`, `name`, `document_type`

**Champs facultatifs :** `metadata`

**Renvoie :** ID des documents créés et statut en attente.

***

### `knowledge_base_add_urls`

Ingestez en masse une ou plusieurs pages web dans une base de connaissances. Chaque URL devient un document distinct et est indexée de manière asynchrone.

**Nécessite :** `knowledge_base_id`, `urls`

**Champs facultatifs :** `metadata`

**Renvoie :** ID des documents créés et statut en attente.

***

### `knowledge_base_get_status`

Obtenez le statut d'indexation de la base de connaissances et le statut de chaque document. Utilisez ceci après avoir ajouté des fichiers ou des URL.

**Nécessite :** `knowledge_base_id`

**Champs facultatifs :** `document_ids`, `cursor`, `items`

***

### `knowledge_base_get_document`

Obtenez un document d'une base de connaissances par ID, y compris les métadonnées du document et le contenu extrait lorsqu'il est disponible.

**Nécessite :** `knowledge_base_id`, `document_id`

***

### `knowledge_base_update_document_metadata`

Remplacez les métadonnées visibles par l'utilisateur d'un document. Les métadonnées sont un objet clé/valeur à un seul niveau et peuvent être utilisées dans les filtres de recherche de la base de connaissances.

**Nécessite :** `knowledge_base_id`, `document_id`, `metadata`

***

### `knowledge_base_delete_document`

Supprimez définitivement un document unique d'une base de connaissances.

**Nécessite :** `knowledge_base_id`, `document_id`

{% hint style="warning" %}
Cette action est irréversible. Confirmez avec l'utilisateur avant de supprimer un document.
{% endhint %}

***

### `knowledge_base_delete`

Supprimez définitivement une base de connaissances et tous ses documents.

**Nécessite :** `knowledge_base_id`

{% hint style="warning" %}
Cela supprime la base de connaissances, tous les documents et les vecteurs sous-jacents. Confirmez avec l'utilisateur avant de l'appeler.
{% endhint %}

***

## Options de requête

Tous les outils de liste prennent en charge :

| Option         | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| **Filtres**    | Affinez par valeurs de champ (EQUALS, CONTAINS, EQ, NEQ, GT, LT, GEQ, LEQ, IN) |
| **Inclut**     | Demandez des données associées en un seul appel                                |
| **Champs**     | Sélectionnez des champs spécifiques à renvoyer                                 |
| **Tri**        | Triez par les champs pris en charge (préfixe `-` pour l'ordre décroissant)     |
| **Pagination** | Contrôlez les résultats avec `page` et `per_page` (100 max)                    |

***

## Fournisseurs d'IA

Valeurs de fournisseurs disponibles pour le filtrage :

* `chat_gpt`
* `gemini`
* `perplexity`
* `google_ai_mode`
* `google_ai_overview`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/fr/developpeurs/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.