API REST

L'API REST de CrunchJunkie donne un accès programmatique en lecture seule aux mêmes données que l'application et le connecteur MCP : vos clients, vos rapports et leurs données en direct, ainsi que les métriques de visibilité IA, en HTTPS simple avec des réponses JSON. Elle est conçue pour les serveurs, les tâches cron, les entrepôts de données et les outils no-code comme Zapier ou Make : partout où vous voulez vos chiffres CrunchJunkie sans qu'une personne clique dans le tableau de bord. Deux choses sont vraies par conception. Elle est en lecture seule : chaque point d'accès v1 récupère, aucun n'écrit, de sorte qu'une clé qui fuit ne peut jamais modifier ni supprimer quoi que ce soit, ni dépenser de budget. Et elle est limitée à l'équipe : une clé appartient à un seul espace de travail et ne renvoie jamais que les données de cet espace de travail. L'API est disponible sur les forfaits Pro, Agency et Scale. (Le connecteur MCP est disponible sur tous les forfaits payants.)

Ouvrez Paramètres → API. Seul un propriétaire ou un administrateur de l'espace de travail peut créer ou révoquer des clés : une clé peut lire tout l'espace de travail, ce n'est donc pas une action réservée aux membres. Donnez un nom à la clé (par exemple « Zapier production ») et cliquez sur Créer. La clé complète, qui ressemble à cj_live_ab12cd34.xxxx…, n'est affichée qu'une seule fois. Copiez-la et conservez-la en lieu sûr (un gestionnaire de secrets, le champ d'identifiants de votre outil) ; nous ne gardons qu'un hash, et ne pouvons donc pas vous la montrer de nouveau. Si vous la perdez, révoquez-la et créez-en une nouvelle. La révocation est instantanée : cliquez sur Révoquer sur une clé et toute intégration qui l'utilise cesse de fonctionner à sa prochaine requête. Les clés n'expirent pas d'elles-mêmes, sauf si vous fixez une expiration. Une clé appartient à l'espace de travail, mais quand un membre part, les clés qu'il y a créées sont révoquées avec lui : quand vous le retirez sous Paramètres → Équipe (le retrait demande confirmation et indique combien), et quand il supprime son propre compte (sa confirmation indique combien). Les clés restent listées ici comme révoquées.

L'URL de base est https://app.crunchjunkie.io/api/v1. Envoyez votre clé comme jeton bearer dans l'en-tête Authorization : curl -H "Authorization: Bearer cj_live_ab12cd34.xxxx…" https://app.crunchjunkie.io/api/v1/clients Chaque réponse est en JSON. Un succès ressemble à { "data": … , "meta": { … } } ; une erreur ressemble à { "error": { "code": "…", "message": "…" } } avec le statut HTTP correspondant (401 non authentifié, 403 portée ou forfait incorrect, 404 introuvable, 429 limite de débit atteinte, 500 erreur serveur).

La v1 est en lecture seule et reprend les outils de lecture MCP, de sorte que les chiffres correspondent exactement à ceux de l'application : • GET /api/v1/clients : vos clients, leurs fournisseurs connectés et leur nombre de rapports. • GET /api/v1/reports?clientId=… : vos rapports (les identifiants servent aux appels ci-dessous). Les rapports dans Supprimés sont écartés ; ajoutez includeDeleted=true pour les lister aussi, marqués deleted: true. • GET /api/v1/reports/{id} : la définition d'un rapport (widgets, configuration des dates). • GET /api/v1/reports/{id}/data?datePreset=…&comparePreset=… : les données assemblées en direct du rapport (KPI, graphiques, tableaux). Un préréglage se résout dans le fuseau horaire de l'espace de travail, comme dans l'application, et la réponse contient le dateRange résolu. Ajoutez brandFilter=branded ou brandFilter=nonbranded pour lire ses widgets Search Console, et tout autre widget qui compte des requêtes de recherche ou des mots clés, pour ce seul groupe. • GET /api/v1/ai-visibility/projects?clientId=… : vos projets de visibilité IA. • GET /api/v1/ai-visibility/projects/{id}/metrics?dateFrom=…&dateTo=…&model=…&market=…&source=…&limit=…&offset=… : les métriques de visibilité IA sur des jours UTC entiers (par défaut les 30 derniers, au plus 180) : chaque marque agrégée sur toutes les réponses (réponses qui la nomment ÷ réponses, avec les réponses comme n et la marge ±), le client par moteur, et les lignes d'instantanés qui les sous-tendent, chacune avec son libellé de moteur et sa source. Le sentiment est sur 0–100 avec 50 pour neutre, et la position 1 signifie nommé en premier ; les deux valent null, avec avgPositionMentions / sentimentMentions et une raison, quand moins de 10 mentions les portent ; meta.note énonce la règle d'agrégation. Un appel renvoie au plus 5 000 lignes d'instantanés (limit, de 1 à 5 000 ; 500 si omis) ; paginez avec offset jusqu'à détenir meta.total lignes. • GET /api/v1/ai-visibility/projects/{id}/prompts?days=…&activeOnly=…&q=… : les prompts suivis, chacun avec sa visibilité agrégée sur ses réponses dans la période et les réponses comme n. activeOnly=true (la valeur par défaut) liste les prompts que les scans interrogent ; activeOnly=false ajoute les prompts en pause, marqués active: false, dont les réponses enregistrées sont conservées. L'API ne modifie jamais un prompt. Un prompt supprimé dans l'application ou via le connecteur MCP disparaît avec toutes les réponses enregistrées pour lui ; cette liste ne l'inclut donc plus, pour les périodes passées non plus. Dans /reports/{id}/data, le prev d'une métrique KPI est la valeur de la période de comparaison. Il vaut null quand il n'y a rien à comparer : pas de période de comparaison, pas de données antérieures pour cette métrique, une période de comparaison que la source n'a pas pu lire, ou un chiffre qui n'existe que tel qu'il est aujourd'hui (comptages de catalogue, totaux d'avis, totaux d'abonnés). C'est un nombre, 0 compris, quand la période de comparaison a été mesurée : 0 est un vrai 0 précédent, à partir duquel il n'y a pas de pourcentage de variation. Chaque widget KPI porte prevNull: true ; meta.note le dit aussi. La value d'une métrique KPI vaut null quand il n'y a pas de chiffre : la lecture a échoué, ou la valeur ne peut pas être calculée (par exemple le coût par conversion avec 0 conversion). Elle ne tient jamais lieu de 0. Un graphique Search Console ou de suivi de positions dans /reports/{id}/data peut porter googleUpdates : les mises à jour du classement Google qui ont eu lieu pendant ses dates, tirées du Search Status Dashboard de Google (nom, lien, début et fin en jours du Pacifique (États-Unis), fin à null tant que le déploiement est en cours). Elles n'indiquent que le moment, pas une cause, et meta.googleUpdates le répète chaque fois qu'un graphique en porte. Un anneau Google Ads par appareil ou par réseau d'un taux, d'une part ou d'une moyenne (CTR, CPC, part d'impressions, coût par conversion, ROAS) n'a aucune tranche dans /reports/{id}/data et dans le get_report_data MCP : son emptyReason est « gads_not_summable », car un tel chiffre par appareil ne fait pas partie d'un total. Une carte Google Ads d'une telle métrique porte notSummable: true, et les chiffres de ses pays sont le taux propre à chaque pays, jamais des parts à additionner. meta.gadsNotSummable le signale pour un tel anneau et meta.geoNotSummable pour une carte de n'importe quelle source (une carte Google Analytics d'Utilisateurs ou d'un taux aussi), et l'aiNote du widget nomme la métrique. Un anneau de toute autre source fonctionne de la même façon depuis la 3.187 : un taux, une moyenne, un ratio, la portée ou les utilisateurs uniques (CTR, ROAS, taux de rebond, position moyenne, utilisateurs, visiteurs) n'a aucune tranche et l'emptyReason « not_summable », et meta.donutNotSummable le signale. Un anneau d'un comptage ou d'un montant garde ses 9 plus grandes tranches et une tranche « Autres » avec le reste, de sorte que ses tranches totalisent toutes les lignes renvoyées par la source (Google Analytics renvoie jusqu'à 10 000 lignes, Matomo et Piwik PRO jusqu'à 1 000 ; les lignes au-delà ne figurent dans aucune tranche). Les noms de colonnes des tableaux (cols) restent des identifiants en anglais ; les cellules affichées sont écrites dans la langue du rapport, telles que le rapport les imprime. Depuis le 14 octobre 2026, cela inclut les cellules Type et Source du tableau des URL citées et les cellules Problème du tableau Santé des sources (en anglais avant), dans /reports/{id}/data et dans le get_report_data MCP. Un widget de sources ou de citations de visibilité IA dans /reports/{id}/data (et dans le get_report_data MCP) qui a écarté des réponses dont les URL viennent de la mémoire du modèle et non d'une recherche indique combien : memoryExcluded sur un tableau, un anneau ou un graphique, fromMemory sur chaque métrique KPI concernée. Ces réponses ne figurent ni au numérateur ni au dénominateur ; les points d'accès de citations et d'écarts de contenu indiquent le même nombre sous le nom answersFromMemoryExcluded. Tout tableau de visibilité IA avec comparaison peut aussi porter withinMargin, les cellules [ligne, colonne] dont la variation n'atteint pas au moins deux fois sa marge d'erreur : dans un tableau de marques, la comparaison d'une cellule ; dans un tableau de prompts, sa cellule Δ Visibilité ; dans un tableau de tags, ses colonnes Δ et la variation sous une valeur. Le rapport les imprime en gris avec « ~ » : lisez donc une telle variation comme inchangée, et lisez ce champ plutôt que le « ~ » du texte. La spécification OpenAPI 3.1 lisible par machine est publiée à l'adresse https://app.crunchjunkie.io/api/v1/openapi.json : importez-la dans Postman, Insomnia ou l'outil de génération de code de votre choix.

Chaque clé a une limite de débit à seau de jetons ; si vous la dépassez, vous recevez un 429 avec un en-tête Retry-After indiquant combien de secondes attendre. Les grandes collections renvoient les lignes les plus récentes avec un meta.total et un indicateur meta.truncated, de sorte qu'une page plafonnée n'est jamais présentée comme l'ensemble complet : restreignez par date ou par modèle pour atteindre des données plus anciennes. Une remarque d'exactitude qui compte si vous calculez vos propres agrégats : les métriques de visibilité IA suivent le contrat de métriques. Agrégez un taux en additionnant les comptages et les exécutions puis en divisant une seule fois (Σ visibilityCount ÷ Σ totalRuns), jamais en moyennant des pourcentages par ligne, et gardez chaque marché (locale) comme sa propre population. L'application le fait pour vous ; faites de même en aval et vos chiffres correspondront aux nôtres.