> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Journal des modifications > Dernières évolutions et modifications de l’API AthenaHQ Cette page présente les évolutions notables de l’API AthenaHQ : fonctionnalités, améliorations et corrections. Consultez-la régulièrement pour connaître les mises à jour susceptibles d’affecter votre intégration. ## Octobre 2026 ### Ajout : filtres de modèles shopping Copilot et Perplexity `POST /api/v1/metrics/shopping` et l’outil MCP `get_shopping_metrics` acceptent désormais `copilot` et `perplexity` dans `filters.models`, en plus de `chatgpt`, `ai_mode` et `gemini`. Shopping Insights propose également ces deux modèles dans son filtre de modèles et ses vues enregistrées. Les fiches produits de Copilot sont capturées dans les nouvelles réponses ; ce changement ne s’applique pas rétroactivement aux réponses antérieures. Les champs de requête, les structures de réponse et les codes de statut existants restent inchangés. ### Ajout : ajouter et retirer des concurrents par MCP `add_competitors` suit de 1 à 25 nouveaux concurrents par site et par appel, chacun avec un nom, une URL (ou `no_website: true`), et éventuellement des identifiants et domaines supplémentaires. `remove_competitors` arrête le suivi de 1 à 25 concurrents selon les identifiants de `get_competitors`. Les deux respectent les règles de Concurrents, dont la vérification de vos propres domaines et la limite de 500 concurrents par site. Ils renvoient un résultat par concurrent : `added`, `already_tracked` ou `rejected` avec motif, et `removed`, `no_change` ou `not_found`. Le retrait est réversible depuis Concurrents. Aucun outil ne réanalyse l’historique ni ne consomme de crédits ; la réanalyse reste dans Concurrents. Les connexions authentifiées nécessitent l’écriture sur Concurrents ; les périmètres de sites des clés API sont respectés. Aucun endpoint REST. ### Ajout : inventaire des clés API de l’organisation `GET /api/v1/api-keys` et l’outil MCP `list_api_keys` listent les métadonnées : créateur, date, périmètre et révocation. REST exige une clé globale ; MCP accepte aussi les connexions OAuth d’administrateur d’organisation, selon les autorisations MCP. Ni secrets ni empreintes ne sont renvoyés. Les clés révoquées sont incluses pour détecter celles créées et révoquées entre deux interrogations. Utilisez les filtres inclusifs `since`/`until`, la pagination `page_num`/`page_size`, des fenêtres qui se chevauchent et une déduplication des alertes par identifiant. C’est un inventaire, pas un journal durable : supprimer le compte du créateur retire ses clés. ### Modification : les clés limitées à un site ne gèrent les membres que si leur créateur l’administre Une clé limitée à un site peut modifier ses membres et invitations uniquement tant que son créateur en est administrateur : propriétaire ou administrateur de l’organisation, administrateur du site ou d’un groupe affecté au site. Cela concerne `PATCH` et `DELETE /api/v1/websites/{website_id}/members/{user_id}`, les invitations de site par `POST /api/v1/invites` et `POST /api/v1/invites/bulk`, et `DELETE /api/v1/invites/website/{invite_id}`. Sinon, HTTP 403 sans modification. Les clés globales, champs et structures de réponse restent inchangés. ### Modification : les requêtes MCP décrivent les limites de chaque cube et plafonnent les limites excessives L’entrée `from` de `query_metrics` et `query_rows` décrit désormais les champs, regroupements autorisés, `limit` maximal et ordre requis pour `orderBy` de chaque cube. Dépasser le maximum ne fait plus échouer l’appel : la requête s’exécute au maximum avec un `notice` explicatif. Par exemple, `limit: 20000` sur `responses` renvoie au plus 100 lignes. Une requête rejetée par le cube, comme un champ inexistant ou un regroupement interdit, renvoie la même erreur 400 suivie de sa description. Noms d’outils, champs d’entrée/sortie et autres statuts inchangés. ### Correction : la recherche de faits de marque se limite à la base de connaissances `GET /api/v1/knowledge-base/facts/search` et `search_brand_facts` pouvaient renvoyer des faits Oracle exclus par défaut de la base et de `get_brand_facts`. Ils ne renvoient plus que les faits approuvés affichés dans la base. Champs et structures inchangés ; certaines recherches renvoient moins de faits. ### Ajout : source de découverte Paysage concurrentiel `start_prompt_discovery` accepte `competitive_landscape`. Cette source recherche sur Google le marché des concurrents suivis et suggère des questions de catégorie, comparaisons entre votre marque et un concurrent suivi, et questions sur ces concurrents. Au moins un concurrent est requis, sinon une erreur de validation est renvoyée. Les restrictions d’offre sont celles de `keyword_gaps`. `get_prompt_discovery_runs` la présente comme toute source. Sources, champs et statuts existants inchangés ; aucun endpoint REST. ### Correction : les pages sources appliquent les tags de prompts `has_all_of` `POST /api/v1/source-pages` et `get_source_pages` traitaient `filters.prompt_tags_operator` `has_all_of` comme `is_any_of`. Ils ne renvoient désormais que les pages citées pour des prompts portant tous les tags listés, et calculent `citation_percentage` et `estimated_impressions` sur ces mêmes prompts. Un tag hors du site renvoie HTTP 403, comme les identifiants de prompt, concurrent et localisation. Une entrée `prompt_tags` inconnue renvoie HTTP 400, comme `has_all_of` avec plusieurs entrées `type:` différentes, que `filters.prompt_type` soit défini ou non. `filters.persona_ids`, `filters.prompt_tags` et `filters.prompt_tags_operator` figurent maintenant dans le schéma de requête. Champs et structures inchangés. ### Ajout : outil MCP `find_more_prompt_discovery` `find_more_prompt_discovery` lance une nouvelle phase d’une étude Découvrir terminée avec son `website_id` et le `run_id` de l’étude ou d’une phase terminée qui la prolonge. Il reprend sources, pays, langue, nombre cible et consignes, évite les questions déjà proposées et lit de nouvelles preuves pour compléter la même étude. Il renvoie `run_id` et `version`, à interroger via `get_prompt_discovery_runs`. Une étude accepte une phase à la fois et deux phases supplémentaires au maximum ; elle s’arrête après une phase trouvant moins de dix prompts nouveaux ou aucune nouvelle preuve. L’outil renvoie alors une erreur motivée ; ce dernier cas porte `reason_code` `sources_exhausted`. L’autorisation de gérer les prompts et les droits sur les sources sont requis. `get_prompt_discovery_runs` regroupe l’étude prolongée en une exécution, accepte le `run_id` de toute phase et ajoute `rounds`, `can_find_more`, `find_more_reason`. Autres champs inchangés ; aucun endpoint REST. ### Ajout : prise de contact par MCP `list_outreach_contacts`, `find_outreach_author`, `draft_outreach_message`, `update_outreach_contact` et `set_outreach_status` permettent de lire les contacts, trouver l’auteur et l’e-mail d’une page citée, rédiger avec les consignes partagées de l’équipe, modifier un contact et changer le statut des pages. Chaque e-mail indique son origine connue (`page_author`, `page_contact`, `hunter`, `manual` ou `null` pour les anciennes données) et jusqu’à cinq autres adresses publiées par la page. Recherche d’auteur et rédaction coûtent les mêmes crédits que dans l’interface. L’écriture nécessite les droits sur Contenu et est auditée. Aucun endpoint REST ajouté. ### Correction : demande OAuth MCP pour les outils protégés Les appels non authentifiés aux outils de compte sur `/api/mcp` et `/api/mcp/claude` renvoient désormais HTTP 401 avec un défi OAuth `WWW-Authenticate`. Auparavant, le défi figurait seulement dans un résultat d’outil HTTP 200, empêchant des clients comme Devin de demander la connexion. Le défi reste aussi dans le corps. Initialisation, découverte des outils, robots publics et appels authentifiés conservent leur comportement. ### Correction : filtres de personas et tags sur les contenus suivis, et onglets de vue `POST /api/v1/content` et `get_tracked_content` ignoraient `filters.persona_ids`, `filters.prompt_tags` et `filters.prompt_tags_operator`. Ces filtres limitent maintenant `total_responses`, `citations`, `citation_percent` et `estimated_impressions` ; toutes les pages suivies restent listées. Un `sheet_id` d’onglet `view`, comme celui par défaut, renvoyait une liste vide ; il liste maintenant le réservoir principal partagé, hors contenus classés dans une feuille, sans les filtres de la vue. Persona ou tag hors site renvoie HTTP 403, comme les identifiants de prompt, concurrent et localisation. Un `prompt_tags` inconnu renvoie HTTP 400, comme `has_all_of` avec plusieurs `type:` différents sans `filters.prompt_type`. Les trois filtres figurent au schéma. Champs et structures inchangés. ### Mise à jour : restrictions régionales des domaines de compte Les nouveaux comptes sont restreints pour les domaines e-mail associés à Cuba, l’Iran, la Corée du Nord, la Russie et la Biélorussie, y compris leurs domaines nationaux internationalisés. En Ukraine, seuls les domaines régionaux de Crimée (Sébastopol compris), Donetsk et Louhansk sont restreints ; les domaines généraux `.ua` sont autorisés. Les invitations directes gardent HTTP 400 en individuel et HTTP 201 avec échecs par cible en groupe. ### Correction : les prompts provisionnés sans sujet restent sans catégorie `POST /api/v1/websites/provision` créait un sujet `Uncategorized` pour les prompts sans `topic`. Ces prompts, et ceux avec un `topic` vide, n’ont désormais aucun sujet, comme dans l’application, et sont affichés Sans catégorie. Un sujet explicitement nommé, y compris `Uncategorized`, est toujours créé tel quel. Les anciens sujets `Uncategorized` ont été retirés et leurs prompts laissés sans sujet. Champs, structures et statuts inchangés. ### Correction : restrictions de domaine sur les invitations directes `POST /api/v1/invites` et `POST /api/v1/invites/bulk` ne peuvent pas créer de nouveaux comptes avec des e-mails finissant par `.ua`, `.ir`, `.ru` ou `.cu`. Les invitations individuelles renvoient HTTP 400 avec `error` ; les groupées conservent HTTP 201 et détaillent les échecs dans `results`. Les comptes existants peuvent toujours être invités et se connecter. ### Mise à jour : les faits similaires sont présentés pour examen `POST /api/v1/knowledge-base/facts` signalait `duplicate` sans ajout dès qu’un fait similaire existait, même non examiné. Le résultat reste `duplicate` avec `fact_id` nul, mais liste aussi les faits similaires dans `matches` (texte, statut, source, appartenance de la source à vos domaines, pilier et date) et fournit `match_token`. Rappelez avec les mêmes faits, ce token, une entrée `decisions` pour chaque correspondance (`approve`, éventuellement avec un nouveau `text`, ou `delete`) et `save_submitted` (true ajoute les faits soumis, false applique uniquement les décisions). Approbation et reformulation suivent les règles des nouveaux faits : source tierce ou affirmation concurrentielle restent en attente. Des décisions ne couvrant pas exactement les correspondances renvoient 400 ; un fait modifié entre-temps renvoie 409, sans écriture. La seconde réponse ajoute `resolved` avec les identifiants approuvés, encore en attente et retirés. Les faits sans correspondance sont ajoutés dès le premier appel comme avant. Champs et statuts existants inchangés ; même comportement pour `add_brand_facts`. ### Modification : URL sources permettant l’approbation automatique des faits Un fait ajouté par `add_brand_facts` ou `POST /api/v1/knowledge-base/facts` avec `source_url` n’est approuvé automatiquement que si l’URL appartient aux domaines du site : motifs d’URL de la marque dans Concurrents et pages/domaines marqués Possédés dans Sources. Auparavant, toute page du domaine enregistrable comptait. `example.com` couvre seulement `example.com` et `www.example.com` ; ajoutez `help.example.com` ou `*.example.com` pour tous les sous-domaines. Une source sur un sous-domaine non couvert revient `pending` ; une autre de vos domaines ou une page Possédée peut désormais revenir `approved`. Faits sans source, champs, structures et statuts inchangés. ### Mise à jour : raison de fin d’une découverte Chaque exécution de `get_prompt_discovery_runs` inclut `reason_code` et `reason`. Le premier indique la raison finale, comme `requested_minimum_not_met` ou `coverage_saturated`, ou l’erreur d’un échec, comme `website_evidence_failed`. `reason` reprend la phrase de Découvrir pour une exécution échouée, vide ou courte, que vous pouvez présenter à l’utilisateur. Les deux valent `null` pendant l’exécution ou en l’absence d’explication. Champs et statuts existants inchangés ; aucun endpoint REST. ### Mise à jour : indications plus claires pour la génération et la collecte Les titres MCP de `create_content` et `start_response_streaming` décrivent désormais le résultat : « Générer un article ou un brief de contenu » et « Exécuter les prompts et collecter les réponses IA ». Les descriptions précisent les modes, l’approbation des briefs et la sélection des prompts. Le convertisseur de schéma conserve les descriptions des champs facultatifs et tableaux. `publish_content` met en avant l’enregistrement de l’URL d’un article déjà publié pour le suivi. Identifiants, valeurs par défaut, validation et contrats REST inchangés. ### Mise à jour : instantanés des nombres de réponses enregistrées `GET /api/v1/response-streaming/status` indique les dates d’observation dans `saved_response_progress.completed_count_observed_at` et `initial_completed_count_observed_at`. Sans date d’observation, le nombre est inconnu. Ces nombres s’actualisent par lots limités en arrière-plan et peuvent rester anciens pendant une panne ; interroger le statut ne relance pas le comptage. Le nombre initial conserve le dernier instantané observé à la première finalisation, parfois antérieur à celle-ci. Les nombres actuels incluent les réponses conservées et peuvent diminuer après suppression. Progression de file, facturation et statuts inchangés. ### Mise à jour : les outils de tags de sources connaissent les tags intégrés Les outils deviennent `source_tags__list`, `source_tags__get_sources`, `source_tags__create`, `source_tags__update`, `source_tags__delete`, remplaçant `list_source_tags`, `create_source_tag`, `update_source_tag`, `delete_source_tag`. La liste inclut tous les tags visibles : Possédé, Concurrent et tags classés automatiquement, avec type, icône, couleur et, pour les tags intégrés, seuls les ajouts/retraits propres au site. `source_tags__get_sources` liste les domaines cités correspondant à un tag personnalisé ou, avec `untagged`, ceux sans tag. `source_tags__update` ajoute/retire des motifs dans la copie locale d’un tag intégré. Créer un homonyme intégré, lister ses sources, le renommer ou le supprimer est refusé. La création accepte icône et couleur facultatives. Aucun endpoint REST modifié. ### Ajout : tags de sources personnalisés par MCP `list_source_tags`, `create_source_tag`, `update_source_tag`, `delete_source_tag` gèrent les tags avec la validation, les droits Analyses, l’audit et l’invalidation de cache d’Athena AI chat. Modification et suppression exigent la révision renvoyée par la liste et signalent leur caractère destructif. Les clients MCP gèrent la confirmation ; les appels autorisés s’exécutent immédiatement. La suppression conserve les sources. Aucun endpoint REST ajouté. Les appels MCP authentifiés émettent aussi un journal de fin structuré : durée en millisecondes, statut, outil et type d’authentification pour examiner la latence. Aucun histogramme ajouté. ### Ajout : identifiants de marque et concurrents par MCP `get_identifiers` lit les noms, alias et domaines comptant comme mentions de votre marque ou d’un concurrent avec `competitor_id`. Il distingue `default_identifiers`, nom et domaine toujours recherchés, de `identifiers`, retirables. `update_identifiers` prend `add` et `remove` selon les règles de Concurrents : nom et domaine non retirables ; doublon déjà listé ou utilisé par une autre marque/concurrent suivi du site refusé sans rien enregistrer. Les nouvelles réponses appliquent le changement immédiatement. L’historique nécessite une réanalyse depuis Concurrents ; `changes_awaiting_backfill` compte les modifications en attente. Droits Concurrents (lecture/écriture selon l’action) et périmètres de clés API respectés. `get_competitors` inchangé ; aucun endpoint REST. ### Mise à jour : effets des outils MCP d’écriture plus explicites `publish_content` s’affiche comme « Marquer le contenu comme publié » : il enregistre une URL pour le suivi, sans publier dans un CMS. `set_prompt_tags` déclare `destructiveHint: true`, car il remplace les tags existants. Les descriptions de génération et collecte précisent les fournisseurs IA externes et la consommation de crédits. Pour générer seulement un brief en brouillon, définissez `auto_approve: false` ; la valeur par défaut est `true`. Sans `schedule_id` ni `prompt_ids`, tous les prompts actifs sont exécutés. Noms, champs, structures et statuts REST inchangés. ### Mise à jour : Gemini dans les métriques Shopping `POST /api/v1/metrics/shopping` accepte `gemini` dans `filters.models`, avec `chatgpt` et `ai_mode`. Athena enregistre désormais les cartes produit Gemini ; les métriques les incluent à partir de cette version, sans historique antérieur. Sans `models`, tous les modèles compatibles Shopping sont couverts, Gemini compris. Comme AI Mode, Gemini ne fournit pas d’offres par vendeur ; `merchant_breakdown` et `offer_summary` ne les comptent pas. `get_shopping_metrics` accepte la même valeur. Champs, structures et statuts inchangés. ### Ajout : importer un article terminé dans Content Hub par MCP `add_content` enregistre un article déjà rédigé, par exemple avec Claude, comme brouillon modifiable, à l’image d’un collage dans l’éditeur vierge. Envoyez `website_id`, le Markdown dans `body`, éventuellement `title` (premier titre du corps par défaut) et `sheet_id`. Aucun modèle ni crédit de contenu utilisé. L’élément a le type `manual`, l’étape `generated` et une version 1 du corps ; `get_content_draft`, `edit_content`, `revise_content`, `get_content_versions` fonctionnent immédiatement. Les liens/images à schéma dangereux, comme `javascript:`, sont remplacés par `#` et comptés dans `unsafe_links_removed`. Rien n’est publié ; appelez `publish_content` avec l’URL après mise en ligne. `create_content` change uniquement sa description pour orienter les articles existants vers `add_content`. Aucun endpoint REST pour le moment. ### Mise à jour : vues enregistrées suivant un sujet Une vue peut suivre un sujet : elle inclut les prompts ajoutés ensuite et exclut ceux supprimés ou déplacés. Les endpoints `/api/v1/metrics` résolvent `filters.saved_view_id` sur les prompts du sujet au moment de la requête. `GET /api/v1/saved-views` et `GET /api/v1/group-saved-views` continuent de lister les identifiants dans `prompts` et `selectedGroupPromptIds` : prompts actuels du sujet ou `00000000-0000-0000-0000-000000000000`, qui ne correspond à rien si le sujet est vide. Même résultat pour `get_saved_views` et `get_group_saved_views`. Champs, structures et statuts inchangés. ### Ajout : découverte de prompts par MCP `start_prompt_discovery` lance une étude asynchrone avec sources, pays, langue, nombre cible et consignes facultatives. `get_prompt_discovery_runs` lit l’historique visible ou interroge le `run_id`, en distinguant attente, exécution, terminé, partiel, échec et annulation. Le lancement conserve les droits de gestion des prompts et sur les sources ; la progression est en lecture seule. Les clients MCP gèrent la confirmation. Aucun prompt n’est suivi automatiquement ; les résultats restent dans Découvrir. Aucun endpoint REST ni contrat existant modifié. ### Mise à jour : cohérence des motifs d’URL et tags de sources Sources et Pages sources utilisent le même moteur de motifs d’URL que le suivi des sites et concurrents. Les domaines ignorent la casse ; les hôtes `www` explicites restent distincts ; les règles de chemin correspondent à des sections, pas à des fragments de nom. Les contraintes de requête conservent la casse et acceptent valeur exacte ou présence de paramètre. Les résumés de domaine utilisent uniquement les règles d’hôte complet. Pages sources garde ses identifiants d’URL normalisés, structure et pagination. La création et le provisionnement de sites préservent le périmètre soumis, la casse du chemin et les contraintes de requête. `acme.com` inclut `www.acme.com` ; `www.acme.com` ne suit que cet hôte. Les anciens motifs sont lus via l’adaptateur jusqu’à la fin de migration. ### Ajout : Avec marque ou Hors marque dans les prompts listés `GET /api/v1/prompts` renvoie `prompt_type` : `branded`, `non_branded` ou `null`. Ces valeurs correspondent aux badges et au filtre `prompt_type` des métriques. Ce ne sont pas des tags ; `tags` ne contient toujours que vos tags personnalisés. Pour définir le type à la création ou modification, envoyez encore `type` à `POST /api/v1/prompts` ou `PATCH /api/v1/prompts/{prompt_id}`, avec `high_intent` pour Avec marque et `discovery` pour Hors marque. `get_prompts` renvoie le même champ. Champs existants inchangés. ### Correction : les exécutions ne retirent plus silencieusement les modèles inconnus `POST /api/v1/response-streaming/start` ignorait les clés inconnues de `selected_models`. `google_ai_overview`, nom utilisé dans les filtres, était donc omis ; seul, il provoquait un rejet pour absence de modèle disponible. Il est maintenant accepté comme alias de `ai_overview`. Toute autre clé inconnue à `true` renvoie 400 avec les identifiants valides ; celles à `false` sont toujours ignorées. Même comportement pour `start_response_streaming`. Champs, structures et autres statuts inchangés. ### Ajout : observations de caractéristiques de marque avec score d’intensité `POST /api/v1/attributes/observations` renvoie les observations individuelles de votre marque et des concurrents, avec extrait de réponse. Chaque ligne porte un `score` de -1 à 1 : son signe suit `positive`, sa magnitude de 0,1 à 1,0 mesure l’intensité de l’éloge ou critique. `null` signifie non évalué, y compris les observations antérieures ; utilisez `score ?? (positive ? 1 : -1)` pour la direction seule. Filtres `entity_ids`, `attribute_ids`, `positive`, tri `intensity` par défaut ou `recent`, pagination `page_num`, `page_size`, `has_more`. `get_attribute_observations` renvoie les mêmes données. Endpoints `/api/v1/attributes` existants inchangés. ### Ajout : combiner plusieurs programmations dans les requêtes MCP et vues `query_metrics` et `query_rows` acceptent un tableau `schedule`, comme `["default", ""]`, combinant les programmations, archivées comprises. L’ordre n’importe pas, les doublons sont supprimés. L’omission sélectionne toujours Default ; une valeur seule reste `"default"` ou l’UUID d’une programmation personnalisée/archivée. Les fréquences différentes sont mélangées dans les totaux et tendances. Les endpoints `/api/v1/metrics` appliquent les programmations multiples d’une vue transmise dans `filters.saved_view_id`. Un `filters.schedule_id` explicite remplace toujours les programmations de la vue par celle-ci. REST `filters.schedule_id` accepte toujours une seule programmation et renvoie `400` pour une liste. `get_prompt_schedules` reste inchangé, sans ligne combinée. ### Correction : les preuves d’accès IA distinguent sondes échouées et refus `POST /api/v1/ai-access/check` ajoute `result.evidence` : observations HTTP nullables par agent, politiques robots.txt indépendantes et synthèse `inconclusive`. Les diagnostics gardent `verdict` (`allowed`, `blocked`, `challenged`, `error`, `not_tested`). Les tokens de politique seuls ne sont pas sondés ; les journaux utilisent le statut des preuves pour ne pas qualifier de bloquée une sonde incomplète. Les pages de défi HTTP 200 sont détectées ; délai dépassé, panne réseau et erreur serveur ordinaire signifient accès inconnu. Google-Extended est évalué comme token robots.txt sans sonde HTTP. Les champs de statut et booléens existants sont conservés. L’ancien champ de formation HTTP Gemini reprend l’observation Googlebot si Google-Extended n’en a pas, sans modifier sa preuve brute `null` ni sa politique indépendante. Les nouveaux consommateurs doivent utiliser `evidence`. Aucun sitemap n’est affirmé sans contrôle. Les requêtes proviennent du réseau Athena et ne garantissent ni accès réel des robots, ni indexation, ni citation. ### Modification : le nombre attendu exclut les variantes jamais générées Dans `GET /api/v1/response-streaming/status`, `saved_response_progress.expected_count` compte les requêtes de base prévues et uniquement les variantes réellement générées. Auparavant égal à `planned_count`, il était impossible à atteindre si la génération produisait moins de variantes, même avec toutes les réponses enregistrées. `planned_count` conserve le plan initial ; l’écart est le nombre de variantes non générées. Les exécutions dont la population initiale était terminée avant ce changement gardent leurs nombres stockés. Champs, types et statuts inchangés. ### Modification : les réponses Grok coûtent 5 crédits pour toutes les organisations Grok coûte désormais 5 crédits par réponse, comme Claude, DeepSeek, Meta AI et Mistral. Les organisations créées avant le 21 juillet 2026 payaient auparavant 1 crédit. Grok utilise maintenant la recherche web xAI plutôt que Perplexity ; ses sources changent à partir de cette version. Filtre `grok`, structures et statuts inchangés. **Lancer sans `selected_models` coûte donc davantage.** `POST /api/v1/response-streaming/start` traite l’omission comme tous les modèles actifs, Grok compris. Fournissez une sélection explicite sans Grok pour éviter ce coût. ### Ajout : accès public des robots IA et extension ChatGPT `check_public_ai_access` vérifie les domaines HTTPS publics sans compte AthenaHQ. Les rapports séparent observations HTTP et politique robots pour recherche, récupération et entraînement, avec preuves nullables et diagnostics. L’extension ChatGPT propose des accès depuis la barre latérale et les discussions, restauration des rapports, copie/export et partage explicite. Les requêtes utilisent des agents de robots depuis AthenaHQ, pas leurs IP vérifiées ; l’accès ne garantit ni indexation ni citation. Analyses de compte, écritures et endpoint authentifié conservent leurs contrats et autorisations. Voir [Accès public des robots](https://docs.athenahq.ai/fr/api-reference/mcp.md#public-ai-crawler-access). ## Septembre 2026 ### Ajout : progression des réponses enregistrées dans le statut de collecte `GET /api/v1/response-streaming/status` inclut `saved_response_progress` : nombres initialement planifié et attendu, réponses distinctes actuellement enregistrées, puis nombre, statut et date du premier résultat final. Une récupération peut augmenter le total actuel sans réécrire cet instantané. La synthèse vaut `null` sans plan initial enregistré ; une population initiale incomplète garde les nombres attendu et initial enregistré à `null`, pas zéro. Les champs `progress` mesurent toujours la file ; seul `state: "completed"` indique la fin des analyses en aval. `get_response_streaming_status` expose le même ajout ; Claude.ai peut demander d’autoriser une fois l’outil mis à jour après déploiement. ### Ajout : preuve par déclaration confirmée dans les constats Oracle MCP `get_oracle_findings` et `get_oracle_finding` incluent `grounding` facultatif pour les constats issus d’une déclaration confirmée par l’équipe : `kind: "confirmed_statement"`, `statement` complet, `confirmationId`, `sourceFindingId` et tous les `facts` justificatifs (`id`, `text`). Utilisez la déclaration complète comme preuve ; `fact_id` et `fact_text` restent des points d’ancrage de compatibilité, sans valeur de preuve indépendante en présence de grounding. Le filtre `fact_id` couvre aussi les faits justificatifs. Les anciens constats gardent leurs preuves. Endpoints REST publics inchangés. ### Ajout : métriques d’une vue enregistrée Les endpoints `/api/v1/metrics` de taux de mention, part de voix, taux de citation et position, cumulatifs ou temporels, acceptent `filters.saved_view_id` de `GET /api/v1/saved-views`. Les filtres de la vue s’appliquent comme au tableau de bord, y compris prompts actifs et tous les modèles par défaut, pour des chiffres identiques à vue et dates égales. `start_date` et `end_date` fixent la fenêtre ; la période enregistrée est ignorée. Un filtre explicite remplace celui de la vue. Une vue d’un autre site renvoie `404` ; un filtre inapplicable renvoie `400` en le nommant. Les outils MCP acceptent le même champ. Voir [Exports de vues enregistrées](https://docs.athenahq.ai/fr/api-reference/saved-view-exports.md) pour une exportation planifiée vers un entrepôt comme Snowflake. Requêtes sans ce champ inchangées. ### Amélioration : création cohérente des programmations `POST /api/v1/websites` et `POST /api/v1/websites/provision` créent ensemble le site et sa programmation Default. Champs et statuts de réussite inchangés. ### Amélioration : dates flexibles dans les filtres MCP `filters.start_date` et `filters.end_date` MCP acceptent dates/horodatages ISO, mois en anglais et dates numériques non ambiguës. Dates impossibles, ordre jour/mois ambigu et périodes explicites inversées renvoient une erreur de validation plutôt qu’un résultat vide silencieux. Une borne de fin sans heure inclut la journée UTC jusqu’à `23:59:59.999Z` ; un horodatage explicite conserve son instant. Contrats REST partenaires inchangés. Voir [Dates MCP](https://docs.athenahq.ai/fr/api-reference/mcp.md#date-range-inputs). ### Correction : les e-mails sont refusés comme URL de site `POST /api/v1/websites` et `POST /api/v1/websites/provision` renvoient `400` si `url` est un e-mail ou contient un nom d’utilisateur, comme `name@example.com` ou `mailto:name@example.com`. Ils étaient interprétés et enregistrés comme URL avec nom d’utilisateur. L’erreur demande de saisir l’adresse du site plutôt qu’un e-mail. Les URL valides avec `@` dans le chemin, comme `example.com/@brand`, restent acceptées. ### Correction : un motif possédé avec chemin ne possède plus tout l’hôte `POST /api/v1/sources` et `POST /api/v1/source-pages` (MCP : `get_sources`, `get_source_pages`) classent les sources selon vos domaines possédés. Un motif comme `reddit.com/user/brand` rendait tout l’hôte `owned` ; il ne couvre plus que les pages de ce chemin, conformément à l’attribution des citations. Il ne marque plus l’hôte entier `owned` dans `/sources`. Les remplacements de type au niveau domaine s’appliquent maintenant aux hôtes possédés seulement comme sous-domaines d’un domaine listé ; un hôte ou chemin explicitement listé reste `owned`. Le remplacement d’URL exacte prime toujours. Structures inchangées ; seules les valeurs `default_source_type` concernées changent. ### Ajout : créer des tags de prompts par MCP `create_prompt_tag` avec `website_id` et `tag` crée un tag ou réutilise un homonyme sans tenir compte de la casse. Résultat : `tag_id`, `tag`, `created`. `set_prompt_tags` remplace la liste complète d’un prompt : incluez les identifiants à conserver ou une liste vide pour tout retirer. Les deux nécessitent l’écriture sur Prompts et respectent le périmètre des clés. Voir [Outils MCP d’écriture](https://docs.athenahq.ai/fr/api-reference/mcp.md#write-tools). ### Ajout : auteur de chaque activité `GET /api/v1/activity` renvoie `actor.user` pour les changements dans l’application : `id` et `email`, ou `null` pour une clé API ou le système. Les clés limitées à certains sites ne voient que leurs membres ; les autres apparaissent `user: null`. Champs existants inchangés. ### Nouveauté : flux d’activité pour les partenaires `GET /api/v1/activity` liste les changements de prompts, sujets et tags dans l’organisation, récents en premier par défaut, avec site, type, identifiants et indication d’usage d’une clé API. Filtres `website_id`, `entity_type`, `change_type`, `since`/`until` ; pagination `page_num`, `page_size`. Pour synchroniser les prompts, fixez une fenêtre par exécution (`since` = précédent `until`, `until` = maintenant moins une minute, `order=asc`) et parcourez les pages. Un appel par synchronisation remplace la relecture de chaque site. `entity_ids: null` demande de relister ce site. Disponible aux clés partenaires. ### Nouveauté : générer des rapports de prospection par API `POST /api/v1/pitches` accepte `website_url`, avec `country` et `language` facultatifs. Utilisez une clé globale et `Idempotency-Key`. La réponse `202` fournit `pitch_id`, `status`, `report_url` partageable ; interrogez `GET /api/v1/pitches/{pitch_id}` jusqu’à la fin. Les rapports apparaissent dans Pitch Workspace. Chaque tentative acceptée consomme une unité. Réutiliser la clé reprend le rapport, même terminé ou échoué. Aucun e-mail envoyé. ### Correction : connexion MCP par clé API depuis Optimizely Opal MCP accepte désormais les clés dans `Authorization: Bearer `, pour les clients ne pouvant envoyer `x-api-key`, comme Optimizely Opal. Organisation, périmètre et droits d’écriture sont conservés. OAuth et `x-api-key` fonctionnent toujours ; REST `/api/v1` exige encore `x-api-key`. Voir [Connecter Optimizely Opal](https://docs.athenahq.ai/fr/api-reference/mcp.md#connect-optimizely-opal). ### Ajout : période d’activité des programmations `GET /api/v1/prompt-schedules` (MCP : `get_prompt_schedules`) renvoie `starts_on` et `ends_on` : premier/dernier jour UTC (`YYYY-MM-DD`) d’exécution d’une programmation personnalisée, ou `null` sans borne. Une programmation `is_active: true` peut ne pas s’exécuter avant/après ces dates ; utilisez-les pour distinguer une saison terminée d’une période active. Default renvoie toujours deux `null`. Champs existants inchangés. ### Amélioration : motif d’arrêt d’une collecte `GET /api/v1/response-streaming/status` (MCP : `get_response_streaming_status`) ajoute `finish_reason` à côté de `state` pour les fins `failed` ou `cancelled` : `credits_exhausted` (épuisés), `credits_paused` (allocation suspendue par le partenaire), `subscription_inactive`, `organization_deleted`, `entitlement_unreadable` (facturation illisible pendant l’exécution ; réponses en attente reprises par réanalyse), `cancelled_by_user`, `responses_failed` (collecte finie avec échecs), `items_stuck`, `attribute_extraction_failed`, `workflow_error`, `stale`. Il vaut `null` pendant l’exécution, après une fin normale ou pour les exécutions antérieures au champ. Cet ajout ne change pas le reste de la réponse. ### Amélioration : destination Content Hub des URL suivies `POST /api/v1/content/track` (MCP : `track_content_urls`) inclut `destination_name` et `content_hub_url` pour chaque résultat créé ou ignoré. Le nom désigne l’onglet contenant la ligne ; le lien ouvre l’élément avec le bon site et onglet. Les lignes partagées utilisent le nom de la vue par défaut, ou « Réservoir partagé » sans vue. Sans `sheet_id`, les URL restent suivies dans le réservoir partagé, indépendamment de l’onglet du navigateur. Une URL déjà suivie renvoie sa destination existante ; un autre `sheet_id` ne la déplace pas. Présentez séparément nombres créés et ignorés, avec destinations et liens. ### Nouveauté : valeurs de colonnes personnalisées lors du suivi d’URL `POST /api/v1/content/track` (MCP : `track_content_urls`) accepte `fields` par URL. Chaque entrée nomme une colonne créée par le client dans l’onglet cible (`column`, sans distinction de casse) et sa `value` : chaîne pour texte, URL http(s) pour lien, nombre, date ISO 8601 (sans heure stockée à minuit UTC, comme le sélecteur Content Hub), booléen pour case, tableau de 50 libellés maximum pour multisélection. Les options manquantes sont créées, celles existantes reconnues sans casse. Les valeurs sont écrites avec la nouvelle ligne, évitant la saisie manuelle après une automatisation. Les URL ignorées conservent leurs valeurs. Colonne inconnue, générée (Ask Athena, approbation, image OG) ou valeur incompatible renvoie `400` avec le champ, sans suivre d’URL. Sans `fields`, comportement inchangé. ### Nouveauté : `POST /api/v1/metrics/shopping` renvoie le tableau Shopping La page Shopping, auparavant inaccessible par API, présente les produits dans les carrousels IA. **POST /api/v1/metrics/shopping** la renvoie en un appel : `summary` (réponses, apparitions de vos produits/concurrents, taux, positions moyennes), `offer_summary` (offres et prix moyen), `top_own_products`, `top_competitor_products`, `competitor_breakdown`, `merchant_breakdown`, `position_distribution`, `price_comparison` et `trend` quotidienne. Les requêtes étant celles de la page, les chiffres correspondent. Corps habituel des métriques : `website_id`, `filters`, dates UTC inclusives `start_date`/`end_date` en `YYYY-MM-DD`. Seuls les filtres de la page sont acceptés : `schedule_id`, `models` (`chatgpt`, `ai_mode`, alors compatibles carrousels), `competitor_ids`, `prompt_tags` avec `prompt_tags_operator`, `target_identifiers`. Tout autre filtre renvoie 400. `top_products_limit` de 1 à 50, défaut 10, règle les deux listes. Taux de 0 à 100 ; positions à partir de 1. Offre payante requise comme dans l’application. Équivalent MCP : `get_shopping_metrics`. Ajout uniquement : tous les endpoints existants restent inchangés. ### Correction : les collectes ponctuelles apparaissent sous Default Les collectes sans programmation, API/MCP comprises, appartiennent à Default. L’historique Manual est déplacé pendant la migration. Le catalogue et la provenance n’émettent que `default` ou des sélections personnalisées. `schedule_id: "manual"` reste accepté comme alias. `POST /api/v1/response-streaming/start` accepte aussi un UUID `schedule_id` facultatif. Une programmation explicite fournit provenance et sélection de prompts ; les options soumises de modèles, variantes, personas et localisations s’appliquent à cette exécution. Une collecte ponctuelle peut coexister avec une collecte programmée de la même programmation. ### Modification : le provisionnement ignore les concurrents sur l’URL du site `POST /api/v1/websites/provision` ignore un concurrent dont l’URL est celle du site ou un chemin sous celle-ci, pour éviter de lui attribuer vos propres citations. Le retrait est journalisé et reflété dans `competitorCount`. Structures inchangées. ### Nouveauté : consommation et historique des crédits par MCP `get_credit_usage` renvoie totaux, tranches temporelles et répartition par réserve débitée. `get_credit_usage_events` renvoie débits, remboursements, actions et site d’origine paginés. Des fenêtres UTC explicites gardent le même intervalle pour les enquêtes mensuelles et pages suivantes. Les utilisateurs authentifiés doivent avoir accès à la facturation de l’organisation ; les clés doivent être globales, pas limitées aux sites. Outils de solde et endpoints REST existants inchangés. ### Modification : accès partenaire aux recommandations via les droits Autumn `POST /api/v1/seo/recommendations` exige `seo_recommendations` dans Autumn, configuré par l’offre ou l’abonnement client. Variables de déploiement et liste d’activation par site ne sont plus nécessaires. Périmètre des clés et droits Contenu du site restent applicables. Les droits sont vérifiés avant acceptation et avant démarrage de l’analyse. Absence : `403` ; contrôle indisponible : `500` sans création. Les tâches non commencées restent en attente si l’accès est invérifiable et libèrent leur place. Attribution/révocation suit le cache partagé : 15 minutes en fonctionnement normal, instantanés vérifiés utilisables jusqu’à une heure pendant une panne Autumn. Limites, structures et lecture autorisée des résultats enregistrés inchangées. ### Nouveauté : recommandations SEO asynchrones pour les partenaires activés `POST /api/v1/seo/recommendations` accepte un brouillon ou une page HTTPS publique et crée une tâche consultable via `GET /api/v1/seo/recommendations/{job_id}?website_id=...`. Résultats : recommandations SEO/recherche IA étayées, preuves et tokens. Même identifiant de requête et données identiques : même tâche ; données différentes : `409`. Jusqu’à 1 000 tâches en attente par site ; quatre workers par site et 16 globalement, avec répartition équitable et reprise des démarrages interrompus. Soumissions et lectures partagent le budget de requêtes de l’organisation (60/minute par défaut) ; soumissions limitées aussi à 120/minute par site. Respectez `Retry-After` sur `429` et espacez les lectures de tâches en attente. Soumettre nécessite `seo_recommendations` Autumn et l’administration Contenu du site ; lire nécessite sa consultation. Les opérations figurent dans `/api/v1/openapi.json` pour la génération de clients, avec les schémas de cette référence. ### Nouveauté : sélectionner une programmation dans les analyses de réponses Métriques dérivées, réponses, sources et attribution acceptent `filters.schedule_id` : `default` ou UUID personnalisé. L’omission sélectionne Default, sans combinaison. Default inclut l’historique antérieur à la transition et les collectes ponctuelles ; l’ancien `manual` est un alias. Les programmations archivées restent consultables, sans sélection Toutes les programmations. `POST /api/v1/looker-studio/data` applique aussi `filters.schedule_id` aux métriques et dimensions, avec caches séparés par programmation. Sans champ, Default reste sélectionnée. Utilisez `GET /api/v1/prompt-schedules?website_id=...` (MCP : `get_prompt_schedules`) pour découvrir noms et sélections. Passez `selection`, pas l’UUID d’une programmation standard. `GET /api/v1/date-range` accepte la même sélection dans `schedule_id`. Les réponses ajoutent la provenance `schedule`, dont `default` pour l’historique. `query_metrics` et `query_rows` acceptent aussi `schedule` au premier niveau. Champs existants inchangés. Les informations globales du site, comme facturation et visites de robots IA, ne sont pas filtrées par programmation. Si votre client MCP a mis en cache les outils ou autorisations, actualisez la liste et réautorisez les outils d’analyse mis à jour si demandé. ### Modification : changer le texte d’un fait en crée un nouveau et archive l’ancien `PATCH /api/v1/knowledge-base/facts/{fact_id}` et `update_brand_fact` ne réécrivent plus le texte en place. Changer `text` crée un fait conservant pilier, provenance et statut d’examen, puis archive l’ancien. Structure inchangée, mais `fact.id` est le nouvel identifiant ; `before` décrit toujours le fait ciblé. Modifier seulement `source_url` ou `confidence` conserve le même fait. Les faits archivés sont exclus de `GET /api/v1/knowledge-base/facts` ; leur `PATCH` renvoie `404`. Le texte des faits issus de réponses IA, masqués comme doublons ou rejetés n’est plus modifiable ici et renvoie `409`. ### Nouveauté : définir, remplacer ou effacer `external_id` avec `PATCH /api/v1/websites/{website_id}` Les partenaires peuvent modifier l’identifiant après création, et plus seulement via `POST /api/v1/websites` ou `POST /api/v1/websites/provision` : * Chaîne `external_id` non vide : définit ou remplace l’association. * `external_id: null` : efface l’association. * Identifiant déjà associé à un autre site de l’organisation : `409`, détenteur actuel dans `existing`. Pour déplacer, effacez l’ancien puis définissez le nouveau. Clé partenaire globale requise. Fonctionne aussi sur les sites supprimés, qui conservent leur `external_id`. ### Modification : les brouillons Optimize peuvent être marqués publiés avant examen `POST /api/v1/content/{content_id}/publish` et `publish_content` ne renvoient plus `409` pour un brouillon Optimize à l’étape `pending` sans examen Athena en cours. Comme la page est déjà en ligne, son URL peut être enregistrée et le suivi de citations commencé avant examen. Même règle pour Suivre dans l’éditeur Content Hub. Pour les autres types, `pending` signifie encore génération et reste refusé, comme un Optimize dont l’examen est actif. Structures inchangées. ### Nouveauté : filtrer les réponses par leurs requêtes de recherche `POST /api/v1/responses` et `get_responses` ajoutent trois filtres propres aux réponses pour examiner les recherches web/cartographiques du modèle : * `filters.has_search_queries` : présence d’au moins une requête non vide. * `filters.search_query_text` : correspondance textuelle sans casse dans les requêtes. * `filters.search_query_text_operator` : `contains` par défaut ou `does_not_contain`. Ils se combinent aux filtres de dates, modèles, prompts, concurrents, localisations et métadonnées. Omission : comportement et structure précédents. ### Modification : écritures de groupes tolérantes aux doublons et grands lots Des requêtes échouant auparavant avec `500` réussissent : * **POST /api/v1/groups** déduplique `website_ids`, crée une adhésion par identifiant et renvoie `201`, avec chaque identifiant une fois dans `websiteIds`. * **PATCH /api/v1/groups/{group_id}** ne renvoie plus `500` si deux requêtes concurrentes ajoutent le même site ; toutes deux renvoient `200`, conformément à l’ignorance silencieuse des membres existants. * Les grands tableaux `add_website_ids` ou `remove_website_ids` dépassant une limite interne sont désormais traités par lots. Les requêtes déjà réussies gardent la même réponse ; aucun chemin, structure ou texte d’erreur changé. ## Septembre 2026 ### Nouveauté : `GET /api/v1/content/items` liste tous les éléments Content Hub, brouillons compris `POST /api/v1/content` ne liste les contenus et métriques qu’après leur génération ; une feuille de brouillons récents semblait donc vide en REST malgré sa présence dans `GET /api/v1/content/sheets`. L’équivalent REST de `list_content` est désormais **GET /api/v1/content/items** : tous les éléments, publiés ou non (brouillons en cours, briefs, snipes, optimisations, découpages, éléments planifiés/échoués, pages suivies), avec identité seule (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, `prompt_ids`, `prompt_count`, horodatages), sans métriques. Filtres `sheet_id`, `content_type`, `stage`, `prompt_id` ; pagination `page_num`/`page_size`. `stage` est l’état brut du flux : `null` sans enregistrement, `generated` pour un texte prêt non publié, manuel compris, `done` après publication ou marquage terminé. Un contenu est publié si son étape est `done` (ou s’il est externe/importé) et s’il a une `url`. La lecture directe du stockage principal sans cache rend l’élément visible dès le retour de `content_id` par `POST /api/v1/content/generate`. Lisez le texte via `GET /api/v1/content/{content_id}`. Ajout uniquement ; `POST /api/v1/content` et tous les autres endpoints restent inchangés. ## Août 2026 ### Nouveauté : valeur de filtre `mistral` Tous les endpoints acceptant `models` acceptent aussi `mistral`. Valeur additive : filtres existants, structures, statuts et comportement sans filtre inchangés. **Les collectes sans `selected_models` coûtent davantage.** L’omission dans `POST /api/v1/response-streaming/start` signifie tous les modèles actifs, désormais Mistral compris. Les intégrations omettant ce champ produiront des réponses Mistral à 5 crédits chacune, comme Claude, DeepSeek et Meta AI. Fournissez la sélection explicite précédente pour la conserver. Les réponses Mistral n’existent que pour les sites ayant activé son suivi : sinon, liste vide sans erreur. Mistral utilise sa propre API et recherche web, sans paramètre pays ; l’attribution géographique reflète le pays du prompt, pas l’origine réseau. Même principe pour `claude`, `deepseek`, `meta_ai`. ### Nouveauté : valeur de filtre `meta_ai` Tous les endpoints acceptant `models` acceptent `meta_ai` pour Meta AI (Muse Spark). Valeur additive : filtres, structures, statuts et omission inchangés. **Les collectes sans `selected_models` coûtent davantage.** L’omission signifie tous les modèles actifs, Meta AI compris. Les intégrations concernées génèrent maintenant des réponses Meta AI à 5 crédits, comme Claude et DeepSeek. Fournissez une sélection explicite pour garder les modèles précédents. Les réponses n’existent que pour les sites ayant activé ce modèle ; sinon, liste vide sans erreur. Meta AI utilise Meta Model API plutôt qu’une session locale extraite : le pays correspond au prompt, pas à l’origine de la requête. Même principe pour `claude` et `deepseek`. ### Nouveauté : `baseCountry` dans la liste des sites **GET /api/v1/websites** et `list_websites` incluent `baseCountry`, marché ciblé, par exemple `"United States"`. Les organisations suivant une marque dans plusieurs pays créent un site par marché ; cette valeur distingue les sites homonymes. Elle est modifiable dans Localisation principale du profil de marque. Les sites n’ayant jamais choisi de pays gardent `"United States"` ; considérez cette valeur non confirmée si le site ne semble pas américain. Ajout sans changement de champ existant ni de statut. Les recherches par identifiant externe (`?external_id=` historique et `GET /api/v1/websites/by-external-id/{external_id}`) n’incluent pas ce champ. Régénérer un client typé ajoute ce champ facultatif. ### Nouveauté : organisation des piliers de la base de connaissances Quatre endpoints permettent de modifier les piliers et déplacer leurs faits. Ils exigent une clé administrateur du site et la base activée pour l’organisation. * **PATCH /api/v1/knowledge-base/pillars/{pillar_id}** change `name`, `description` ou `status`, au moins un, uniquement les champs fournis. Renommage homonyme : `409`. Statut `published` ou `archived` ; archiver masque le pilier et retire ses faits de la génération sans les supprimer. MCP : `update_pillar`. * **POST /api/v1/knowledge-base/facts/move** classe 1 à 50 faits sous un pilier publié, non classés ou issus d’autres piliers. Statut d’examen inchangé ; seuls les faits approuvés d’un pilier publié alimentent la génération. Identifiants absents dans `not_found_ids`, sans échec, pour des reprises idempotentes. MCP : `move_brand_facts`. * **POST /api/v1/knowledge-base/pillars/merge** fusionne 1 à 20 sources vers un pilier publié : faits déplacés, liens conservés avec le signal le plus fort, puis sources supprimées. Reprise stricte : sources manquantes rejetées ; relisez les piliers avant de réessayer. MCP : `merge_pillars`. * **POST /api/v1/knowledge-base/pillars/delete** supprime définitivement 1 à 20 piliers et leurs faits, sans déclassement ni annulation. Le résultat donne nom et nombre de faits, car les piliers ne sont plus consultables. Comme `delete_brand_facts`, OAuth MCP exige le rôle administrateur, pas seulement l’écriture sur les connaissances. MCP : `delete_pillars`. ### Nouveauté : retirer l’accès d’un membre avec `DELETE /api/v1/groups/{group_id}/members/{user_id}` Retire l’adhésion directe au groupe et les adhésions explicites aux sites actuellement dans ce groupe. * Résultat : adhésion de groupe retirée et nombre d’adhésions de sites retirées. Reprises et cibles absentes valides sont idempotentes, avec zéro retrait. * Appartenance à l’organisation, autres groupes et sites extérieurs conservée. Un autre groupe peut maintenir l’accès à un site partagé. * Les membres d’organisation renvoient `409`, car leur accès global resterait. Clé globale requise ; impossible de retirer le propre utilisateur de la clé. ### Modification : la direction d’un attribut sélectionne la perception par réponse Les quatre endpoints gardent chemins et structures, mais les attributs sont désormais des sujets neutres. `positive` identifie la série d’observations positives ou négatives, sans classer définitivement le nom. * `GET /api/v1/attributes`, `POST /api/v1/attributes/cumulative`, `POST /api/v1/attributes/competitors`, `POST /api/v1/attributes/time-series` acceptent `positive` facultatif au premier niveau. * Omission : `true`, pour préserver les requêtes. `positive: false` sélectionne les observations négatives du même identifiant. * Les pourcentages restent la prévalence directionnelle parmi les réponses échantillonnées, analysées avec succès et mentionnant l’entité. Une réponse avec les deux directions compte une fois dans chaque série ; une réponse analysée sans affirmation d’attribut reste au dénominateur. Champs, chemins et enveloppes inchangés. ### Modification : limites explicites de taille des corps Les écritures de sites, provisionnement et prompts valident désormais les tailles et renvoient `400` en cas de dépassement. Les plafonds dépassent largement l’usage réel (166 identifiants maximum stockés, prompts inférieurs à 1 000 caractères), préservant les requêtes existantes valides. OpenAPI déclare `maxLength`/`maxItems`. * `POST /api/v1/websites` : `url`, 2 048 caractères. * `POST /api/v1/websites/provision` : `url` 2 048, `name` 255 ; `identifiers` 200 entrées de 500 caractères, concurrents compris ; `competitors` 500 entrées avec mêmes plafonds nom/URL ; `prompts` 10 000 entrées avec `text` 2 000 caractères. Le plafond de 500 concurrents actifs s’applique à toute l’API ; création au-delà : `400`. * `POST /api/v1/prompts` et `PATCH /api/v1/prompts/{prompt_id}` : 2 000 caractères. Lot de création toujours limité à 1 000. * `POST /api/v1/prompts` : 60 requêtes/minute/site, indépendamment du plafond organisation. Avec 1 000 prompts/appel, environ 60 000 prompts/minute/site ; dépassement : `429`. Régénérer un client typé ajoute ces annotations. Noms et formes inchangés ; seuls les `400` de taille et `429` de création par site s’ajoutent. ### Précision : progression à 100 % avant fin de l’analyse `GET /api/v1/response-streaming/status` garde structure et états. `progress` mesure la collecte ; `state` couvre l’ensemble. `state: "running"` peut coexister avec `progress.percentage: 100` pendant sentiment et attributs. Seul `state: "completed"` indique que l’analyse est prête. Aucune migration client. ### Nouveauté : modifier le rôle d’un membre avec `PATCH /api/v1/groups/{group_id}/members/{user_id}` Auparavant, l’API permettait d’inviter via `POST /api/v1/invites/bulk` et de lire le rôle via `GET /api/v1/groups/{group_id}/members`, sans le changer autrement qu’en retirant/réinvitant ou via l’interface. Le nouvel endpoint suit ceux des membres de site et d’organisation : * Fournissez exactement un `role` (`admin`/`viewer`) ou `role_id`, système ou personnalisé de `GET /api/v1/roles`. La réponse reprend `role_id` et son slug, comme `role` dans la liste. * Seuls les membres explicites `access_type: "group"` sont ciblés. Un membre global n’a pas de rôle de groupe et renvoie `409` ; modifier son rôle global affecterait tous les groupes et sites. * Clé globale requise, sans modification de son propre utilisateur. Pas de protection du dernier administrateur de groupe : les administrateurs d’organisation gardent l’accès. * **Les rôles hors `admin`/`viewer` sont appliqués mais mal affichés dans l’interface.** Editor ou Billing Manager accorde ses droits réels sur tous les sites du groupe, mais la liste affiche encore Lecteur pour tout rôle non administrateur. Préférez `admin`/`viewer` si le client doit voir le rôle exact. ### Nouveauté : prompts ciblés dans `GET /api/v1/content/{content_id}` Ajout de `prompts` et `prompts_total`. `prompts` liste les cibles de rédaction, identifiants de `prompt_ids` à la génération, avec texte, sujet et statut. Cette association était auparavant uniquement inscriptible. * Ordre d’association ancien d’abord, maximum 100 ; total non tronqué dans `prompts_total`. Les imports peuvent en associer des milliers ; vérifiez le total. Au-delà de 100, non récupérables actuellement. * `status` : `active`, `paused`, `deleted`. Les supprimés restent listés, car le contenu les ciblait et Content Hub les affiche ; ils ne figurent pas dans `GET /api/v1/prompts`, d’où le texte intégré. * Tableau vide : aucun ciblage enregistré, normal pour les pages importées ou suivies externes. Cela diffère de `POST /api/v1/content/prompts`, qui liste les prompts dont les réponses ont **cité** la page sur une période. Le ciblage dépend du contenu, sans nécessiter de citation. Champs additifs, clients existants inchangés. ### Nouveauté : réponses allégées avec `include_response` et `compact_sources` `POST /api/v1/responses` et `get_responses` acceptent deux booléens pour retirer les champs les plus volumineux. Valeurs par défaut et corps sans options inchangés ; `page_size` reste limité à 100. * **`include_response: false`** omet `response`, environ 2,2 Ko par ligne. * **`compact_sources: true`** remplace les objets `sources` par `source_domains`, domaines racines dédupliqués et triés, environ 3,1 Ko de moins par ligne. Hôtes en minuscules sans `www.` initial, sous-domaines conservés : `shop.example.com` reste distinct de `example.com`. Combinez-les avec `filters.variation_filter: ["variation"]` pour exporter les variantes en volume, en conservant prompt de base, variante, modèle, `mentioned`, `cited` et domaines, pour environ un dixième de la taille. **Avant de régénérer un client typé :** `response` et `sources` ne sont plus `required`, puisqu’ils peuvent être absents. Ils deviennent facultatifs et peuvent provoquer une erreur de compilation même sans utiliser les options. Sans options, la réponse réelle ne change pas. Les champs retirés sont absents, pas vides, pour éviter d’assimiler une réponse vide à une absence de texte du modèle. `GET /api/v1/responses/{response_id}` renvoie toujours la ligne complète. ## Juillet 2026 ### Nouveauté : suivre des URL existantes avec `POST /api/v1/content/track` L’API ne pouvait auparavant associer une URL qu’à un contenu généré par Athena via `publish`. Les pages existantes, articles invités, publications partenaires ou contenus rédigés ailleurs n’étaient pas suivables. Le nouvel endpoint et `track_content_urls` enregistrent jusqu’à 500 URL dans Content Hub par appel : * Chaque URL devient une ligne externe ; l’URL normalisée relie citations et métriques, permettant l’attribution immédiate des réponses suivies. Ni publication, génération ni coût en crédits. Les domaines tiers sont acceptés. * Idempotence par URL, quel que soit le type existant : aucun doublon. `created` et `skipped` sont séparés ; les ignorés fournissent `content_id` et `type` pour distinguer page déjà suivie et contenu généré avant d’enchaîner les appels. Les paramètres de suivi d’une même page sont regroupés. * Les lignes n’ont pas de texte, inutile au suivi. Content Hub peut récupérer le corps à la demande sur les pages externes sans texte. * `sheet_id` facultatif classe les lignes dans un onglet ; `title` par URL remplace le titre dérivé du chemin. ### Modification : `get_tracked_content` conserve les pages externes/importées après extraction Ces pages disparaissaient de `POST /api/v1/content` et `get_tracked_content` après récupération du texte, car un état interne les excluait du filtre publié. Suivi, attribution et affichage dans Content Hub continuaient ; seule la liste les masquait. Elles sont désormais toujours listées, avec leurs métriques intactes ; les comptes peuvent donc augmenter. Les contenus générés restent inchangés et n’apparaissent qu’une fois publiés. ### Nouveauté : modifier et supprimer les faits de marque Les intégrations peuvent corriger et retirer les faits qu’elles ajoutent. Clé administrateur de site et base activée requises pour les deux endpoints. * **PATCH /api/v1/knowledge-base/facts/{fact_id}** change uniquement `text`, `source_url`, `confidence` fournis ; `source_url: ""` efface la source. Modifier le texte recalcule son embedding ; collision avec un fait frère de la même réponse IA : `409`. Les autres doublons relèvent de la déduplication de la base. Statut d’examen inchangé. MCP : `update_brand_fact`, par clé API ou OAuth lié à l’organisation avec écriture sur les connaissances. * **POST /api/v1/knowledge-base/facts/delete** supprime définitivement 1 à 50 faits, sans annulation. Les absents du site sont dans `not_found_ids`, sans échec, pour les reprises idempotentes. Les faits quittent la recherche sémantique et la synthèse du pilier est régénérée sans eux. MCP : `delete_brand_facts`, avec rôle administrateur pour OAuth comme dans l’interface. ### Nouveauté : `external_id` partenaire partout dans les objets de site Les endpoints renvoyant des sites incluent l’identifiant partenaire pour les rapprocher de vos propres données, car `websiteUrl` change si l’URL principale est modifiée : * `GET /api/v1/groups`, `GET /api/v1/groups/{group_id}` et réponse de `PATCH /api/v1/groups/{group_id}` : chaque objet `websites` porte `externalId`, ou `null`, en plus de celui du groupe. Renvoyé depuis début juillet, désormais documenté. * `GET /api/v1/users/{user_id}/websites` : chaque entrée inclut `external_id`, selon sa convention snake\_case. Uniquement pour les clés partenaires ; les réponses clients directs omettent le champ. L’association est créée via `external_id` dans les créations/provisionnements. La liste des sites et leur recherche par identifiant externe l’exposaient déjà. ### Modification : les listes excluent Oracle par défaut (`include_oracle`) `GET /api/v1/knowledge-base/facts` et `get_brand_facts` excluent désormais les faits Oracle de toutes les listes. Non affectés aux piliers, ils pouvaient dominer le corpus avec des millions de lignes et masquer les faits sélectionnés par l’utilisateur. Structure inchangée, sélection différente. `include_oracle=true` les réintègre et se combine aux filtres ; `include_oracle=true&unfiled=true` rétablit l’ancienne sélection non classée. `GET /api/v1/knowledge-base/facts/search` reste alors inchangé et recherche tout le corpus approuvé ; un résultat avec `pillar: null` peut manquer de la liste par défaut. ### Nouveauté : marquer publié avec `POST /api/v1/content/{content_id}/publish` L’API permettait de créer, réviser et approuver un brief, mais pas de déclarer l’article effectivement publié sur votre site. Sans URL de jointure, il restait non publié et sans suivi de citations. Le nouvel endpoint et `publish_content` ferment cette boucle. Appelez après mise en ligne avec l’URL publique exacte : * L’URL sert de clé citations/métriques, sans protocole ni barre finale ; `acme.com/blog/post` est accepté. Requête et fragment sont exclus de la clé hors YouTube, mais conservés dans l’affichage ; les UTM ne rompent donc pas l’attribution. YouTube garde les paramètres contenant l’identifiant vidéo. * Date de publication enregistrée et étape `done`, rendant le contenu publié dans Content Hub et `get_tracked_content`. * Première publication : article terminé `generated`. Briefs, générations en cours/échouées ou publication CMS planifiée : `409` motivé. * Un nouvel appel sur du contenu publié change seulement l’URL, sans changer la date initiale ; `already_published` distingue les cas. Les pages externes/importées, déjà en ligne par définition, n’ont qu’une mise à jour d’URL. C’est la seule manière de définir une URL par API ; `PATCH /api/v1/content/{content_id}` reste limité au titre. ### Nouveauté : outil MCP `list_content` pour les brouillons non publiés `get_tracked_content` n’affichant les métriques qu’après la génération, une feuille de brouillons paraissait vide sans leurs identifiants. `list_content` liste tous les éléments, publiés ou non : brouillons, briefs, snipes, optimisations, découpages, éléments planifiés/échoués et pages suivies. Identité seule (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, horodatages), sans métriques ; filtres `sheet_id`, `content_type`, `stage`, pagination `page_num`/`page_size`. L’identifiant d’un onglet de type vue (`sheet_type` de `get_content_hub_sheets`) liste le réservoir partagé sans les filtres de vue. `stage` est l’état brut : `null` sans flux (nombreuses pages externes/importées), sinon `pending_brief`, `generated`, `done`, `scheduled`, `failed`, etc. Publication Content Hub : `done` ou page externe/importée, avec `url` ; éléments manuels à `generated`. Lecture primaire sans cache : visible dès `create_content`, avant approbation, génération ou publication. `get_tracked_content` et `POST /api/v1/content` inchangés. ### Nouveauté : modifications exactes avec `POST /api/v1/content/{content_id}/edit` `revise` confie une consigne à un modèle et enregistre sa rédaction. `edit` et `edit_content` offrent un remplacement déterministe : paires exactes rechercher/remplacer, sans IA. * Chaque `find` doit correspondre exactement une fois au corps actuel. Zéro correspondance ou plusieurs fait échouer tout l’appel avec `400`, sans enregistrement ; allongez l’extrait pour le rendre unique. * Jusqu’à 20 modifications dans l’ordre, chacune voyant les résultats précédents. Le lot devient une seule version restaurable. * `expected_version_number` facultatif, issu du brouillon, renvoie `409` si une version a été créée depuis votre lecture (révision, édition, restauration). L’enregistrement automatique peut changer le corps sans version ; les ancres détectent cet écart si `find` a bougé ou disparu. Les descriptions de `revise` et `brief/revise` précisent que leur texte est généré par IA et ne reprend pas nécessairement votre formulation littérale. ### Correction : une révision ciblée pouvait remplacer l’article par un extrait `POST /api/v1/content/{content_id}/revise` et `revise_content` pouvaient n’enregistrer que le passage modifié après une consigne étroite. Une révision nettement plus courte, sans demande de réduction, est maintenant relancée avec une exigence explicite de document complet. Si elle reste fragmentaire, `500` sans changement du brouillon. Aucune troncature silencieuse ; l’ancien texte reste restaurable. La réponse ajoute les entiers `body_word_count` et `previous_body_word_count`. `body` contient toujours l’article de remplacement complet. Le même garde-fou s’applique à `POST /api/v1/content/{content_id}/brief/revise`, dont la structure reste inchangée. ### Modification : `filters.competitor_ids` devient strict sur les contenus `POST /api/v1/content` et `POST /api/v1/content/prompts` conservaient aussi les réponses sans aucun concurrent. Désormais, une réponse n’est comptée que si elle mentionne au moins un identifiant fourni, comme pour Réponses et Sources. Sans filtre, comportement inchangé. Les deux endpoints sont aussi nettement plus rapides. ### Nouveauté : `fact_review` pour la génération `POST /api/v1/content/generate` et `create_content` acceptent en mode draft `{ topic_ids, kept_claim_ids, excluded_claim_ids }` dans `fact_review`. La génération utilise exactement les piliers examinés et faits conservés, sans sélection autonome. `pinned_claim_ids` n’influence plus la sélection en présence d’un examen, qui tient déjà compte des épingles, mais reste enregistré pour l’affichage. Base activée requise ; `fact_review` avec `kb_mode: "none"` ou hors mode draft renvoie une validation. La génération est aussi strictement limitée aux faits classés sous un pilier, qu’ils soient sélectionnés automatiquement, épinglés ou conservés. Les identifiants de faits non classés sont retirés et signalés dans le résultat de sélection. Classez-les pour les utiliser. ### Nouveauté : `409` si vous supprimez le site portant l’abonnement `POST /api/v1/websites/{website_id}/delete` renvoie `409 Conflict` pour un site portant l’abonnement de l’organisation. Les offres sont désormais globales, mais les anciens abonnements restent attachés à un site. Le supprimer laissait l’abonnement et ses crédits bloqués, avec facturation active et zéro crédit ailleurs. L’endpoint refuse maintenant avec motif pour permettre d’annuler ou déplacer l’offre. Autres suppressions et restaurations inchangées. Traitez `409` comme une demande de régler la facturation, pas comme une erreur à réessayer. ### Correction : `cited` était toujours `false` `POST /api/v1/responses` et `GET /api/v1/responses/{response_id}` lisaient une valeur jamais alimentée par l’ingestion. `cited` est maintenant calculé à la lecture : `true` si une source correspond au domaine racine du site, sans distinction de protocole, `www.` ou casse. Cela corrige tout l’historique, sans changement de structure. Les métriques agrégées étaient calculées séparément et correctes. ### Correction : texte nul pour les brouillons à l’étape brief `GET /api/v1/content/{content_id}` et `get_content_detail` renvoyaient `status`, `brief`, `body` et tous les champs de génération à `null` avant rédaction de l’article, même si le brief existait. Les brouillons `generated_brief` en attente d’approbation renvoient maintenant brief et statut. Un identifiant inconnu/inaccessible garde `404` ; `null` signifie désormais réellement vide. ### Nouveauté : `stage` dans le statut du contenu `GET /api/v1/content/{content_id}/status` et `get_content_status` ajoutent `stage` au `status` normalisé inchangé (`running | succeeded | failed`). `running` ne distinguait pas génération active et attente de brief avec `auto_approve: false`. L’étape brute vaut `scheduled`, `pending`, `pending_brief`, `generated_brief`, `pending_article`, `generated`, `done`, `failed` ou `null` avant démarrage. À `generated_brief`, appelez `POST /api/v1/content/{content_id}/brief/approve` plutôt que continuer d’attendre. ### Nouveauté : examiner et faire évoluer briefs et brouillons Vous pouvez lire, réviser en langage naturel et restaurer briefs et articles, sans recommencer chaque contenu en le payant à nouveau. Chaque révision crée une version récupérable. Brief et article partagent l’historique complet `get_content_versions`. **Phase brief.** `auto_approve: false` dans la génération arrête à `generated_brief`. Le contrôle existait ; ces endpoints le rendent utilisable de bout en bout. * **GET /api/v1/content/{content_id}/draft** : texte courant, corps, brief, méta-description, statut et dernière version. Lecture ciblée ; le détail standard reste complet. MCP : `get_content_draft`. * **POST /api/v1/content/{content_id}/brief/revise** : réécrit selon une consigne, par exemple ajouter les objections tarifaires. MCP : `revise_brief`. * **POST /api/v1/content/{content_id}/brief/approve** : approuve le brief actuel et lance l’article ; consomme des crédits. MCP : `approve_brief`. **Phase article.** * **POST /api/v1/content/{content_id}/revise** : réécrit depuis le texte actuel ; aucun numéro de version à fournir. MCP : `revise_content`. * **POST /api/v1/content/{content_id}/versions** : historique récent d’abord avec libellé, mode de production et auteur. POST pour la pagination dans le corps. MCP : `get_content_versions`. * **GET /api/v1/content/{content_id}/versions/{version_id}** : texte complet d’une version, pour comparer deux passages. MCP : `get_content_version`. * **POST /api/v1/content/{content_id}/versions/{version_id}/restore** : rétablit le texte comme brouillon actuel. MCP : `restore_content_version`. Trois précisions : * **Restaurer ne supprime rien.** Le texte restauré devient une nouvelle version ; les versions intermédiaires restent consultables et l’historique note la restauration. * **Réviser ne régénère pas.** Cela ne relance ni recherche ni extraction. Réviser un brief après l’article le corrige pour une future régénération, sans réécrire l’article. * **Impossible pendant une génération.** Ces endpoints renvoient `409` ; attendez `succeeded` dans le statut. ### Nouveauté : créer des vues enregistrées par MCP Une vue enregistre des filtres nommés et apparaît pour tous les membres du site. * **`create_saved_view`** : `name`, `icon` facultatif et `filters` stocké tel quel, sans conversion de casse des clés, limité à 64 Ko. Aucun équivalent REST volontairement : c’est un flux d’assistant, pas d’intégration partenaire. Une vue créée par clé API n’a pas de propriétaire : `user_id` vaut `null` dans `GET /api/v1/saved-views`, et l’interface indique une création API. Seuls les administrateurs du site peuvent la modifier ou supprimer dans l’interface. Les vues de connexion authentifiée sont attribuées à l’utilisateur, comme celles créées dans le tableau de bord. ### Nouveauté : plugin AthenaHQ pour ChatGPT AthenaHQ est disponible comme plugin officiel ChatGPT, sans connecteur MCP personnalisé ni mode développeur. [Installez le plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69), connectez-vous à AthenaHQ et mentionnez `@AthenaHQ` pour interroger part de voix, citations, sources, prompts suivis et autres données. Connexions en lecture seule comme les autres connexions authentifiées. Voir [Serveur MCP](https://docs.athenahq.ai/fr/api-reference/mcp.md). ### Nouveauté : attributs de perception de marque Cette version introduit la lecture des attributs et de leur fréquence dans les réponses. Depuis août 2026, ce sont des caractéristiques neutres, comme **Tarification** ou **Réactivité de l’assistance**, avec observations positives et négatives du même attribut, sans sentiment fixe. * **GET /api/v1/attributes** : attributs suivis `{ "id", "name", "positive" }` pour découvrir les identifiants. MCP : `get_attributes`. * **POST /api/v1/attributes/cumulative** : nombres et pourcentages par attribut sur la période ; ceux sans mention ont `response_count` 0, sans omission. MCP : `get_attribute_metrics`. * **POST /api/v1/attributes/competitors** : comparaison par concurrent, chacun avec son dénominateur ; ceux sans réponses sont omis. MCP : `get_competitor_attribute_metrics`. * **POST /api/v1/attributes/time-series** : tendance quotidienne d’un `attribute_id`, marque et concurrents côte à côte ; jours sans données à zéro, sans trous. À la lecture : `positive` sélectionne une direction, et le même identifiant peut avoir les deux. `percentage` porte sur les réponses **analysées** ; l’extraction étant échantillonnée, les non analysées sont exclues du dénominateur. ### Nouveauté : écritures dans la base de connaissances Ajoutez des faits de façon déclarative : texte, URL source et pilier facultatifs, sans statut ni approbation. Le traitement complet applique déduplication, contrôles d’approbation et classement, puis rapporte son choix par fait. `outcome` (`approved`, `pending`, `duplicate`) est extensible ; considérez toute valeur inconnue comme non finale. Clé administrateur de site et base activée requises. * **POST /api/v1/knowledge-base/facts** : 1 à 50 faits, résultat `{ "index", "outcome", "fact_id", "pillar_id" }`. Les faits avec `pillar_id` y sont classés ; les autres sont routés automatiquement et peuvent rester non classés. MCP : `add_brand_facts`, clés API et OAuth lié à l’organisation avec écriture sur les connaissances. * **POST /api/v1/knowledge-base/pillars** : `name`, `description` facultative. Un nom existant renvoie le pilier avec `created: false`, pour l’idempotence. MCP : `create_pillar`. ### Nouveauté : lectures de la base de connaissances Lisez les faits approuvés de marque, chacun étayé par une source, par exemple une déclaration de prix, et les piliers qui les organisent. Les quatre endpoints exigent la base activée ; sinon `403` avec `"Knowledge Base is not enabled for this organization"`. * **GET /api/v1/knowledge-base/facts/search** : recherche sémantique combinant similarité vectorielle et texte intégral, y compris les faits sans pilier. MCP : `search_brand_facts`. * **GET /api/v1/knowledge-base/facts** : faits récents d’abord, pagination par décalage ; filtres pilier, statut (approuvé par défaut), source et `unfiled=true` sans pilier publié. MCP : `get_brand_facts`. * **GET /api/v1/knowledge-base/pillars** : piliers non archivés, nombres de faits approuvés, présence de synthèse et dernière recherche. MCP : `get_pillars`. * **GET /api/v1/knowledge-base/pillars/{pillar_id}/document** : synthèse Markdown ; `document: null` si le pilier existe sans document. MCP : `get_pillar_document`. ### Nouveauté : découvrir les personas Les identifiants `persona_id`, auparavant sans moyen de résoudre leurs noms, sont maintenant consultables. * **GET /api/v1/personas** : personas du site avec `{ "id", "name", "description", "prompt_count" }`. MCP : `get_personas`. ### Nouveauté : génération de contenu par API et MCP Passez d’une analyse à l’action sans quitter l’API ou l’assistant : repérez une lacune puis rédigez du contenu. * **POST /api/v1/content/generate** : modes `draft` (nouveau contenu depuis `prompt_ids`), `snipe` (dépasser une URL concurrente), `optimize` (améliorer une URL existante), `slice` (découper une URL en articles). Renvoie des `content_ids` durables à interroger. Crédits de contenu et clé administrateur du site requis. MCP par clé : `create_content`. * **GET /api/v1/content/{content_id}/status** : statut normalisé `running`, `succeeded`, `failed`, à interroger pour chaque identifiant. MCP : `get_content_status`. * **PATCH /api/v1/content/{content_id}** : renomme le titre ; l’URL reste l’identité stable non modifiable. Clé administrateur requise. MCP : `rename_content`, initialement `update_content`, renommé pour préciser sa portée. * **DELETE /api/v1/content/{content_id}** : suppression définitive sans annulation. Clé administrateur requise. MCP : `delete_content`. Liste et détail étaient déjà disponibles : **POST /api/v1/content**, **GET /api/v1/content/{content_id}**, `get_tracked_content`, `get_content_detail`. ### Nouveauté : gestion des sujets Créez un sujet, récupérez son `id` et utilisez-le dans `prompts[].topic_id`. * **GET /api/v1/topics** : sujets actifs et nombre de prompts actifs ; résout un nom en identifiant. MCP : `get_topics`. * **POST /api/v1/topics** : `name`, `description` facultative ; un homonyme actif renvoie l’existant avec `created: false`, pour reprises/imports idempotents. Clé administrateur requise. MCP : `create_topic`. * **PATCH /api/v1/topics/{topic_id}** : change `name` et/ou `description` sans affecter métriques ni regroupement liés à l’identifiant. Clé administrateur requise. MCP : `update_topic`. * **DELETE /api/v1/topics/{topic_id}** : suppression réversible ; prompts conservés et actifs par défaut, reclassables. `delete_prompts=true` supprime aussi les prompts actifs de façon réversible. Recréer le même nom restaure le sujet. Clé administrateur requise. MCP : `delete_topic`. ### Nouveauté : découvrir les tags de prompts Les UUID nécessaires à `prompt_tags` dans **GET /api/v1/prompts** et `tag_ids` dans **POST /api/v1/prompts** sont maintenant exposés. * **GET /api/v1/prompts** ajoute `tags`, `[{ "id", "name" }]` trié par nom, vide sans tag. Champs existants inchangés. * **GET /api/v1/prompt-tags** liste `{ "id", "name", "prompt_count" }` pour alimenter un sélecteur sans lire tous les prompts. MCP : `get_prompt_tags`. ### Modification : création de l’entité de facturation dans les réponses de provisionnement `billingEntityCreated` indique si l’entité portant les crédits a été créée. À `false`, site/groupe existe mais ne peut pas encore détenir de crédits : leur affectation renvoie `400` jusqu’à réparation. Pour un groupe, **PATCH /api/v1/groups/{group_id}** avec `billing_enabled: true` ; pour un site, contactez l’assistance. L’échec était auparavant silencieux. Concerne **POST /api/v1/websites** et **POST /api/v1/websites/provision** (toujours), et **POST /api/v1/groups** si `billing_enabled` demandé. ### Nouveauté : outils MCP d’écriture Les connexions par **clé API** disposent d’outils identiques aux endpoints REST : champs snake\_case, validation et audit. Les connexions OAuth restent alors en lecture seule, sans ces outils. * `create_prompts`, `update_prompt`, `set_prompts_status`, `delete_prompt` : opérations POST/PATCH/DELETE `/api/v1/prompts...`. * `create_location`, `update_location`, `delete_location` : opérations `/api/v1/locations...`. * `start_response_streaming` : POST `/api/v1/response-streaming/start` ; statut déjà disponible via `get_response_streaming_status`. Les lectures manquantes complètent aussi la couverture des procédures : `get_user_by_email` ([POST /api/v1/users/by-email](https://docs.athenahq.ai/fr/api-reference/team-management/look-up-user-by-email.md), clé globale), `get_response_detail` (GET /api/v1/responses/{response_id}), `get_groups`, `get_group_detail` (GET /api/v1/groups..., clé globale), `check_ai_access` (POST /api/v1/ai-access/check), `get_position_distribution` (POST /api/v1/metrics/position/distribution). ### Nouveauté : gestion des rôles Listez les rôles système (Administrateur, Éditeur, Lecteur, Facturation) et personnalisés, puis créez, modifiez ou supprimez les rôles personnalisés avec leurs matrices par catégorie. Création réservée à Enterprise ; **clé globale** pour tous. * **GET /api/v1/roles** : rôles et matrices résolues. * **POST /api/v1/roles** : crée un rôle personnalisé, offre Enterprise. * **GET /api/v1/roles/{role_id}** : détail. * **PATCH /api/v1/roles/{role_id}** : modifie les autorisations. * **DELETE /api/v1/roles/{role_id}** : supprime s’il n’est plus attribué. ### Modification : attribuer tout rôle avec `role_id` Invitations et modification des membres d’organisation acceptent `role_id`, système ou personnalisé, en plus de `role` (`admin`/`viewer`) toujours compatible. Les deux sont mutuellement exclusifs. Concerne **POST /api/v1/invites**, **POST /api/v1/invites/bulk**, **PATCH /api/v1/organizations/members/{user_id}**. ### Modification : taux de mention relatif dans les métriques Les entrées marque/concurrent des taux de mention et parts de voix ajoutent `relative_mention_rate` : pourcentage de mentions de l’entité parmi les réponses citant au moins une marque suivie (0 à 100), comme le mode Relatif du tableau de bord. `mention_rate` reste absolu, sur toutes les réponses. Champs existants inchangés. Concerne **[POST /api/v1/metrics/mention-rate/cumulative](https://docs.athenahq.ai/fr/api-reference/metrics/cumulative-mention-rate.md)**, **[POST /api/v1/metrics/mention-rate/time-series](https://docs.athenahq.ai/fr/api-reference/metrics/mention-rate-over-time.md)**, **[POST /api/v1/metrics/share-of-voice/cumulative](https://docs.athenahq.ai/fr/api-reference/metrics/cumulative-share-of-voice.md)**, **[POST /api/v1/metrics/share-of-voice/time-series](https://docs.athenahq.ai/fr/api-reference/metrics/share-of-voice-over-time.md)**, par entrée et par jour pour les séries. Outils : `get_mention_rate_cumulative`, `get_mention_rate_time_series`, `get_share_of_voice_cumulative`, `get_share_of_voice_time_series`. ### Nouveauté : déclencher une collecte par API Lancez les requêtes IA pour les prompts du site, ingérez les réponses et suivez la progression, comme dans l’interface. * **[POST /api/v1/response-streaming/start](https://docs.athenahq.ai/fr/api-reference/basics/start-response-streaming.md)** : tous les prompts actifs ou jusqu’à 1 000 sélectionnés ; modèles, variantes, personas et localisations facultatifs. Renvoie `workflow_id`, `status: "running"`. Clé administrateur requise. * **[GET /api/v1/response-streaming/status](https://docs.athenahq.ai/fr/api-reference/basics/get-response-streaming-status.md)** : dernier état `idle`/`running`/`completed`/`failed`/`cancelled`, progression `pending`, `processing`, `completed`, `failed`, `total`, `percentage`. `workflow_id` cible une exécution. ### Nouveauté : trouver un utilisateur par e-mail Résolvez `user_id` dans l’organisation avec l’e-mail dans le corps pour éviter son inscription aux journaux. * **[POST /api/v1/users/by-email](https://docs.athenahq.ai/fr/api-reference/team-management/look-up-user-by-email.md)** : `user_id`, nom, `access_type` (`organization` ou `website`) si membre ; sinon `404`, indistinguable d’un e-mail inconnu pour éviter l’énumération. Clé globale requise. ### Nouveauté : retirer un utilisateur de plusieurs sites Supprimez ses adhésions explicites en lot, en complément de la liste de ses sites. * **[DELETE /api/v1/users/{user_id}/websites](https://docs.athenahq.ai/fr/api-reference/team-management/remove-user-from-websites.md)** : `website_ids` en paramètre de requête, séparés par virgules, maximum 100. Sans adhésion explicite, `not_a_member` plutôt qu’échec ; idempotent. Clé globale requise. ### Modification : filtrer les prompts par tags [GET /api/v1/prompts](https://docs.athenahq.ai/fr/api-reference/basics/get-prompts.md) accepte `prompt_tags` et `prompt_tags_operator` : `is_any_of` par défaut ou `has_all_of`. Tous les identifiants doivent appartenir à `website_id`. Aussi disponible dans `get_prompts` MCP. ### Nouveauté : lire un contenu individuel Le détail complet inclut le texte : `brief`, et `body` pour brouillons, réécritures, snipes, texte rédigé et pages extraites. `status` permet l’interrogation pendant génération ; `generated_brief` indique le brief prêt et l’article encore en rédaction. * **[GET /api/v1/content/{content_id}](https://docs.athenahq.ai/fr/api-reference/content/get-content-detail.md)** : détail, `brief`, `body`, URL citées, liens et `status`. MCP : `get_content_detail`. ### Modification : filtre de contenu `manual` `content_type` accepte **`manual`** : texte rédigé par l’utilisateur directement dans l’éditeur vierge, distinct du contenu généré ou importé. Valeurs existantes inchangées. Concerne **POST /api/v1/content**. ## Juin 2026 ### Modification : `role` d’un membre devient son slug Les listes renvoient le nom normalisé en minuscules sans espaces plutôt que seulement `admin`/`viewer`. Rôles intégrés : `admin`, `viewer`, `editor`, `billing` ; rôle personnalisé avec son identifiant, par exemple `contentmanager`. Les vérifications admin/viewer restent compatibles ; les anciens rôles non admin présentés comme viewer montrent leur rôle réel. Concerne **GET /api/v1/organizations/members**, **GET /api/v1/websites/{website_id}/members**, **GET /api/v1/groups/{group_id}/members**, **GET /api/v1/users/{user_id}/websites**. ### Nouveauté : gérer les prompts par API Créez, modifiez, mettez en pause/réactivez et supprimez les prompts avec les mêmes validations géographiques et de propriété que dans l’interface. * **[POST /api/v1/prompts](https://docs.athenahq.ai/fr/api-reference/basics/create-prompts.md)** : jusqu’à 1 000 par requête, avec sujet, géographie, personas/localisations/tags et pause facultatifs. * **[PATCH /api/v1/prompts/{prompt_id}](https://docs.athenahq.ai/fr/api-reference/basics/update-prompt.md)** : texte, type, volume, sujet, géographie ou localisations ; instantané avant/après. * **[PATCH /api/v1/prompts/status](https://docs.athenahq.ai/fr/api-reference/basics/pause-or-unpause-prompts.md)** : pause/réactivation groupée dans une transaction. * **[DELETE /api/v1/prompts/{prompt_id}](https://docs.athenahq.ai/fr/api-reference/basics/delete-prompt.md)** : suppression réversible si réponses existantes, définitive sinon. ### Nouveauté : gérer les localisations par API Créez, modifiez, supprimez les localisations. `country` ignore la casse et est stocké sous son libellé canonique ; les prompts associés sont validés selon ce pays. * **[POST /api/v1/locations](https://docs.athenahq.ai/fr/api-reference/basics/create-location.md)** : pays et prompts facultatifs. * **[PATCH /api/v1/locations/{location_id}](https://docs.athenahq.ai/fr/api-reference/basics/update-location.md)** : nom, pays, prompts ; instantané avant/après. * **[DELETE /api/v1/locations/{location_id}](https://docs.athenahq.ai/fr/api-reference/basics/delete-location.md)** : suppression réversible. ## Mai 2026 ### Nouveauté : serveur MCP pour Claude, ChatGPT et autres assistants Connectez AthenaHQ via le [Model Context Protocol](https://docs.athenahq.ai/fr/api-reference/mcp.md). Le serveur en lecture seule expose métriques, prompts, réponses, contenus, sources, concurrents et rapports de prospection pour interroger votre visibilité en langage naturel. * **Claude.ai** ou **ChatGPT** : connecteur personnalisé et connexion AthenaHQ, sans clé. * Autres clients, dont **Claude Code** : clé API dans `x-api-key`. URL du serveur : `https://api.athenahq.ai/api/mcp`. ### Nouveauté : endpoints Sources Récupérez les données de sources citées par API ou MCP (`get_sources`/`get_source_pages`). Chaque ligne est `owned`/`competitor`/`partner`/`third_party` selon concurrents, partenaires affiliés et remplacements de type par site. * **[POST /api/v1/sources](https://docs.athenahq.ai/fr/api-reference/sources/list-sources-by-root-domain.md)** : domaines racines les plus cités, métriques de citation, mention, mention de marque et impressions sur la période ; filtres, recherche, tri, pagination. * **[POST /api/v1/source-pages](https://docs.athenahq.ai/fr/api-reference/sources/list-source-pages-per-url.md)** : une ligne par `normalized_url`, mêmes métriques et tendance quotidienne `daily_mentions`. ### Nouveauté : endpoints Pitch Workspace Lisez les rapports de prospection par API. Ces ressources étant globales à l’organisation, une **clé globale** est requise ; les clés de site renvoient `403 Forbidden`. * **[GET /api/v1/pitches](https://docs.athenahq.ai/fr/api-reference/pitch-workspace/list-pitches.md)** : rapports non supprimés de l’organisation, métadonnées d’entreprise et état. * **[GET /api/v1/pitches/{pitch_id}](https://docs.athenahq.ai/fr/api-reference/pitch-workspace/get-pitch-report.md)** : concurrents et statistiques de mentions/sentiment, prompts générés, attributs positifs/négatifs de la cible et des concurrents, principaux domaines citants, métriques `total_responses`, `brand_mentions`, `sentiment_score`, `response_rate`. ### Nouveauté : endpoints Content Hub Lisez URL suivies, métriques de citations/impressions et répartition des prompts par URL. Le reporting GEO regroupe ainsi contenus Athena et contenus tiers : placements de liens, Reddit, publications partenaires. * **[GET /api/v1/content/sheets](https://docs.athenahq.ai/fr/api-reference/content/list-content-hub-sheets.md)** : onglets du site ; appelez d’abord pour découvrir les `sheet_id` filtrables. * **[POST /api/v1/content](https://docs.athenahq.ai/fr/api-reference/content/list-tracked-content.md)** : liste paginée avec citations, taux, impressions estimées et total de réponses sur la période. Filtres `sheet_id`, `content_type`, `mentioned` et filtres standard. * **[POST /api/v1/content/prompts](https://docs.athenahq.ai/fr/api-reference/content/per-content-prompt-citation-breakdown.md)** : prompts dont les réponses citent un contenu, avec nombres et pourcentages par prompt. Fonctionne avec contenu lié à un sujet ou tiers non classé. ### Nouveauté : endpoint des vues enregistrées Récupérez les ensembles nommés de filtres de tableau de bord réutilisables dans le produit. * **[GET /api/v1/saved-views](https://docs.athenahq.ai/fr/api-reference/basics/get-saved-views.md)** : vues du site avec filtres, icône et métadonnées du créateur. ### Nouveauté : vues enregistrées de groupe Ces vues conservent des filtres partagés entre les sites du groupe, sans se limiter à un site. * **[GET /api/v1/group-saved-views](https://docs.athenahq.ai/fr/api-reference/basics/get-group-saved-views.md)** : fournissez `group_id` ; autorisation selon l’organisation du groupe. ## Avril 2026 ### Mise à jour : plusieurs pays par prompt [GET /api/v1/prompts](https://docs.athenahq.ai/fr/api-reference/basics/get-prompts.md) renvoie `countries` avec tous les pays ciblés et `is_primary`. Le principal est en premier, puis les autres par ordre alphabétique. * `countries: [{ country: string, is_primary: boolean }]` : nouveau champ, tableau vide sans pays. * `country: string` : obsolète mais maintenu ; pays principal, sinon premier alphabétique, sinon `"United States"`. Les nouvelles intégrations doivent lire `countries`. ### Nouveauté : supprimer et restaurer les sites La suppression retire le site de l’organisation et arrête son traitement ; la restauration le rétablit avec tout son historique. Parcours recommandé aux partenaires pour les résiliations et réactivations. * `POST /api/v1/websites/{website_id}/delete` : supprime. * `POST /api/v1/websites/{website_id}/restore` : réactive. Clé globale requise ; les deux sont idempotents et renvoient 200 si l’état cible est déjà atteint. ### Mise à jour : inviter dans des groupes [POST /api/v1/invites](https://docs.athenahq.ai/fr/api-reference/team-management/create-invite.md) accepte `type: "group"` avec `group_id`, donnant accès à tous ses sites. [POST /api/v1/invites/bulk](https://docs.athenahq.ai/fr/api-reference/team-management/bulk-invite-to-websites-or-groups.md) accepte `group_ids`, maximum 50, exclusif avec `website_ids`, pour plusieurs groupes. Comme pour organisation/site, `invite_method: "direct"` ajoute immédiatement, créant le compte si nécessaire, sans e-mail ; `invite_method: "email"` crée et envoie une invitation en attente. **Clé globale** requise. Les membres globaux ne peuvent pas être invités aux groupes individuels puisqu’ils y ont déjà accès en cascade. ### Nouveauté : gestion d’équipe Gérez membres et invitations, automatisez provisionnement, rôles et nettoyage sans le tableau de bord. **Lister les membres et accès** * **[GET /api/v1/organizations/members](https://docs.athenahq.ai/fr/api-reference/team-management/list-organization-members.md)** : e-mail, nom et rôle de tous les membres ; clé globale. * **[GET /api/v1/websites/{website_id}/members](https://docs.athenahq.ai/fr/api-reference/team-management/list-website-members.md)** : utilisateurs autorisés avec `access_type` `organization` pour accès implicite global, `website` pour adhésion explicite. Clé globale ou de site. * **[GET /api/v1/users/{user_id}/websites](https://docs.athenahq.ai/fr/api-reference/team-management/list-user-websites.md)** : sites accessibles à un utilisateur dans l’organisation ; clé globale. **Modifier et retirer les membres** * **[PATCH /api/v1/organizations/members/{user_id}](https://docs.athenahq.ai/fr/api-reference/team-management/update-organization-member-role.md)** : rôle global ; clé globale. * **[DELETE /api/v1/organizations/members/{user_id}](https://docs.athenahq.ai/fr/api-reference/team-management/remove-organization-member.md)** : retire de l’organisation et nettoie les adhésions de site résiduelles en transaction atomique ; clé globale. * **[PATCH /api/v1/websites/{website_id}/members/{user_id}](https://docs.athenahq.ai/fr/api-reference/team-management/update-website-member-role.md)** : rôle du site ; clé globale ou de site. * **[DELETE /api/v1/websites/{website_id}/members/{user_id}](https://docs.athenahq.ai/fr/api-reference/team-management/remove-website-member.md)** : accès explicite au site ; clé globale ou de site. **Révoquer les invitations en attente** * **[DELETE /api/v1/invites/org/{invite_id}](https://docs.athenahq.ai/fr/api-reference/team-management/revoke-organization-invite.md)** : révocation réversible d’organisation ; clé globale. * **[DELETE /api/v1/invites/website/{invite_id}](https://docs.athenahq.ai/fr/api-reference/team-management/revoke-website-invite.md)** : révocation réversible de site ; clé globale ou de site. Les écritures empêchent de modifier le propre utilisateur de la clé, le propriétaire ou le dernier administrateur de l’organisation. ### Mise à jour : `user_id` dans les invitations directes [POST /api/v1/invites](https://docs.athenahq.ai/fr/api-reference/team-management/create-invite.md) et [POST /api/v1/invites/bulk](https://docs.athenahq.ai/fr/api-reference/team-management/bulk-invite-to-websites-or-groups.md) ajoutent `user_id` en réussite **uniquement pour `invite_method: "direct"`**. L’utilisateur étant trouvé/créé immédiatement, vous pouvez appeler la gestion des membres sans recherche supplémentaire. Les invitations e-mail l’omettent pour empêcher l’énumération des comptes d’autres organisations par adresse. Changement rétrocompatible. ### Nouveauté : provisionner un site (bêta) Créez un site entièrement configuré en un appel sans assistant d’accueil, avec concurrents, prompts et programmation facultatifs. En bêta, les schémas peuvent évoluer. * **[POST /api/v1/websites/provision](https://docs.athenahq.ai/fr/api-reference/basics/provision-website.md)** : site et options ; clé globale. ### Nouveauté : crédits d’un groupe Récupérez le solde actuel, ventilé entre crédits mensuels et ponctuels. * **[GET /api/v1/credits/group](https://docs.athenahq.ai/fr/api-reference/billing/get-group-credits.md)** : solde du groupe ; clé globale. ## Mars 2026 ### Nouveauté : lire et modifier un groupe Récupérez un groupe par identifiant, renommez-le et ajoutez ou retirez des sites. * **[GET /api/v1/groups/{group_id}](https://docs.athenahq.ai/fr/api-reference/groups/get-group.md)** : groupe et sites associés. * **[PATCH /api/v1/groups/{group_id}](https://docs.athenahq.ai/fr/api-reference/groups/update-group.md)** : nom, ajouts et/ou retraits de sites. Clé globale requise pour les deux. ### Nouveauté : invitations groupées aux sites Invitez un utilisateur dans plusieurs sites en un appel, avec traitement indépendant et résultats par site pour faciliter l’accueil dans l’organisation. * **[POST /api/v1/invites/bulk](https://docs.athenahq.ai/fr/api-reference/team-management/bulk-invite-to-websites-or-groups.md)** : jusqu’à 50 sites, invitation directe ou e-mail. ## Février 2026 ### Nouveauté : endpoints de groupes Organisez plusieurs sites dans une entité de votre organisation et gérez-la par API. * **[GET /api/v1/groups](https://docs.athenahq.ai/fr/api-reference/groups/list-groups.md)** : tous les groupes et leurs sites. * **[POST /api/v1/groups](https://docs.athenahq.ai/fr/api-reference/groups/create-group.md)** : crée un groupe avec un ou plusieurs sites. Clé globale requise pour les deux. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.