OLAB Assist Connexion
Développeurs

API, webhooks et MCP

Intégrez vos données de suivi OLAB Assist aux outils de votre agence. Version 1, en lecture seule, incluse dans l’offre Agency.

Présentation

OLAB Assist offre aux agences cinq façons d’utiliser leurs données de suivi en dehors du tableau de bord. Toutes lisent les mêmes données et respectent le même contrat versionné : ce que vous voyez dans l’une correspond à ce que vous voyez dans les autres.

  • API REST : importez les sites, scores, contrôles, réponses IA, l’historique des scores, les tendances et les changements dans un CRM, un entrepôt de données ou un outil de reporting.
  • Webhooks : recevez un événement JSON signé dès qu’un audit se termine ou que de nouvelles réponses IA arrivent, sans avoir à interroger l’API en boucle.
  • Serveur MCP : connectez Claude, ChatGPT, Cursor ou tout client Model Context Protocol et posez vos questions sur vos sites en langage courant.
  • Looker Studio : créez des rapports clients sur les scores, les problèmes et la visibilité IA avec le connecteur OLAB Assist.
  • Notion : gardez à jour une page Notion avec vos sites, vos problèmes et vos réponses IA, sans code.

Vous préférez un guide pas à pas ? Les guides d’intégration détaillent la configuration de chacune : Notion, Looker Studio, Slack, Discord, Zapier et Make, API REST et MCP.

L’API, les webhooks, Looker Studio et Notion sont inclus dans l’offre Agency. Le serveur MCP est disponible dès l’offre Founders & Makers : en lecture seule dans les offres Founders & Makers et Growth, avec des outils d’action dans l’offre Agency. Le propriétaire du compte gère les clés et les webhooks dans Intégrations.

Authentification

Créez une clé sur la page Intégrations. La clé complète n’est affichée qu’une seule fois ; nous n’en conservons qu’une empreinte (hash). Envoyez-la avec chaque requête :

curl https://api.olabassist.com/api/v1/sites \
  -H "Authorization: Bearer olab_YOUR_KEY"

Les clés sont en lecture seule et limitées à votre espace de travail : une clé ne voit jamais que les sites du compte qui l’a créée. Révoquez une clé sur la page Intégrations et elle cesse immédiatement de fonctionner. Si le compte quitte l’offre Agency, ses clés cessent de fonctionner jusqu’à son retour.

Requêtes et limites

  • URL de base : https://api.olabassist.com/api/v1. GET /api/v1 renvoie la liste des endpoints.
  • Tous les endpoints utilisent GET et renvoient du JSON : { "data": …, "api_version": "v1" }. Les listes paginées renvoient aussi next_cursor.
  • Les horodatages sont au format ISO 8601, en UTC. Les scores vont de 0 à 100.
  • Limite de débit : 120 requêtes par minute et par clé. Au-delà, vous recevez 429 avec retryAfterSeconds.
  • Partout où un chemin contient {site}, vous pouvez indiquer l’id du site ou son domaine, par ex. /sites/example.com.

Endpoints

GET /account

Votre offre, vos limites et votre consommation.

GET /sites

Chaque site surveillé avec son dernier score et ses problèmes ouverts.

{
  "data": [{
    "id": "k3Jd9x2Lq",
    "domain": "example.com",
    "brand_name": "Example",
    "status": "active",
    "created_at": "2026-09-01T10:00:00.000Z",
    "next_scan_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "regressions_last_7_days": 0,
    "report_url": "https://olabassist.com/r/…",
    "app_url": "https://olabassist.com/app/?site=k3Jd9x2Lq"
  }],
  "api_version": "v1"
}

GET /sites/{site}

Tout ce qui précède, plus ai_visibility (réponses vérifiées, nombre de réponses qui vous mentionnent, nombre de réponses qui citent votre site comme source, votre rang parmi les marques suivies, sentiment), share_of_voice par marque suivie, top_sources citées par les assistants, competitors, questions et engines.

GET /sites/{site}/findings?status=fail,warn

Les contrôles du dernier audit avec la preuve et le correctif (summary, where et, s’il existe, un code prêt à coller). Sans status, tous les contrôles sont renvoyés.

GET /sites/{site}/tasks

Les problèmes ouverts du dernier audit sous forme de tâches pour un agent de code IA (Claude Code, Cursor ou équivalent), en Markdown : contexte, étapes, code, façon de remplir chaque espace réservé à partir du site lui-même, conditions pour que la tâche soit terminée et ce qu’il ne faut pas modifier. Renvoie { "data": { "markdown": "…", "tasks": 5 } }. Paramètres : finding (un id de contrôle issu de /findings, pour une seule tâche) et lang (en, tr, es, de ou fr). Un contrôle réussi renvoie 404 NO_TASK.

GET /sites/{site}/answers

Les réponses IA enregistrées, des plus récentes aux plus anciennes. Chaque réponse comprend la question, l’assistant (engine), si votre marque a été mentionnée (named) et citée comme source (cited), son rang (rank), le sentiment (sentiment), chaque marque suivie présente dans la réponse et les sources citées.

Paramètres : engine, question_id, since (date ISO), limit (1–500, 100 par défaut), cursor, include_answer=true pour le texte complet de la réponse. Lorsque next_cursor n’est pas nul, passez-le comme cursor pour obtenir la page suivante.

GET /sites/{site}/history

Le score après chaque audit, du plus ancien au plus récent (limit jusqu’à 200).

GET /sites/{site}/trends

Des séries temporelles pour les graphiques et les rapports, regroupées par day, week (lundi) ou month (UTC). Paramètres : from et to (AAAA-MM-JJ, inclus ; par défaut les 90 derniers jours, jusqu’à deux ans), bucket (la valeur par défaut dépend de la période). La réponse contient periods (dates de début des périodes), series (un tableau par métrique, aligné sur periods, avec null en l’absence de données), un catalog qui décrit chaque série (unit : score, pct, count ou rank ; better : up ou down) et les changements (changes) de la période.

Séries : score.overall, score.seo, score.geo, score.aeo, score.aio (dernier audit de chaque période), issues.fail, issues.warn, ai.visibility, ai.cited, ai.positive, ai.negative (pourcentages), ai.position (rang moyen lorsque la marque est mentionnée), ai.answers, engine.<assistant> et intent.<intent> (visibilité en %), et brand.<competitor domain> (part des réponses qui mentionnent ce concurrent).

GET /sites/{site}/changes

Ce qui a changé entre deux audits : les nouveaux problèmes (new), ce qui s’est dégradé (worse) et ce qui s’est amélioré (better, corrigé). Paramètres : since, limit.

Erreurs

Les erreurs utilisent les codes de statut HTTP et un corps JSON : { "error": "NOT_FOUND", "message": "…" }.

  • 401 clé absente, non valide ou révoquée
  • 403 API_NOT_IN_PLAN l’espace de travail n’a pas l’offre Agency
  • 404 le site ne fait pas partie de cet espace de travail
  • 405 l’API est en lecture seule
  • 429 limite de débit atteinte

Webhooks

Ajoutez une adresse https sur la page Intégrations et choisissez les événements à recevoir. Chaque événement est envoyé en POST avec un corps JSON :

{
  "id": "evt_4Hh2…",
  "type": "scan.completed",
  "api_version": "v1",
  "created_at": "2026-10-05T10:00:00.000Z",
  "data": {
    "site": { "id": "k3Jd9x2Lq", "domain": "example.com", "app_url": "…" },
    "audit_id": "…",
    "checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "changes": [{ "finding_id": "seo-title", "kind": "worse", "from": "pass", "to": "warn", "title": "Title tag is too long", "at": "…" }],
    "report_url": "https://olabassist.com/r/…"
  }
}

Événements

  • score.dropped : le score global a baissé d’au moins le seuil du webhook (10 % par défaut, de 1 à 90 % par webhook). Ancien et nouveau score, baisse en points et en pourcentage, et variation de chaque catégorie.
  • visibility.lost : un assistant IA mentionnait votre marque dans sa dernière réponse à une question suivie et ne la mentionne plus. Comprend l’assistant, la question et named_instead, les concurrents qu’il recommande à la place.
  • visibility.gained : un assistant mentionne désormais votre marque alors qu’il ne la mentionnait pas auparavant, avec son rang.
  • scan.completed : un audit est terminé (quotidien, manuel ou revérification). Scores, nombre de problèmes et changements.
  • answers.updated : de nouvelles réponses IA pour une question suivie, une entrée par assistant, au même format que /answers.
  • site.created et site.deleted.

Utilisez Envoyer un test sur la page Intégrations pour recevoir un événement ping.

Slack, Discord, Asana, ClickUp

Chaque webhook a un format de message. Collez l’adresse d’un webhook entrant Slack ou Discord et OLAB Assist envoie une alerte lisible d’une ligne avec un lien, dans la langue du compte (les adresses Slack et Discord sont détectées automatiquement). Pour Asana, ClickUp, Trello, HubSpot et d’autres, utilisez le format JSON avec Zapier, Make ou n8n : un déclencheur « Catch webhook » suivi de « Create task » transforme chaque score.dropped ou visibility.lost en tâche. Chaque envoi porte OLAB-Signature ; Slack et Discord l’ignorent simplement.

Vérifier la signature

Chaque requête porte OLAB-Event, OLAB-Delivery et OLAB-Signature: t=<unix seconds>,v1=<hex>. La signature est un HMAC-SHA256 de t + "." + raw body calculé avec le secret de signature de votre webhook. Comparez-la en temps constant et rejetez les horodatages trop anciens :

// Node.js
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Nouvelles tentatives

Répondez avec un statut 2xx en moins de 10 secondes. Toute autre réponse entraîne une nouvelle tentative après environ 5 minutes, 30 minutes, 2 heures, 6 heures et 24 heures. Après 25 échecs d’envoi consécutifs, le webhook est suspendu ; réactivez-le sur la page Intégrations. Utilisez id pour ignorer un événement déjà traité.

Serveur MCP

L’endpoint MCP est https://api.olabassist.com/mcp (Streamable HTTP). Il expose les endpoints de l’API sous forme d’outils en lecture seule : list_sites, get_site, get_findings, get_tasks, get_ai_answers, get_score_history, get_trends, get_changes. Avec l’offre Agency, le serveur propose aussi quatre outils d’action, soumis aux mêmes limites que le tableau de bord : add_question (suivre une nouvelle question ; chaque assistant y répond immédiatement), start_scan (auditer un site tout de suite ; compte parmi les audits à la demande par jour de l’offre), mark_task_applied (indiquer la tâche telle que get_tasks la mentionne ; les audits suivants montrent l’avant et l’après) et add_competitor. Avec les offres Founders & Makers et Growth, ces outils n’apparaissent pas.

Clients qui acceptent des en-têtes (Claude Code, Cursor et autres) :

{
  "mcpServers": {
    "olab-assist": {
      "url": "https://api.olabassist.com/mcp",
      "headers": { "Authorization": "Bearer olab_YOUR_KEY" }
    }
  }
}

Claude Code : claude mcp add --transport http olab-assist https://api.olabassist.com/mcp --header "Authorization: Bearer olab_YOUR_KEY"

Les clients qui n’acceptent qu’une URL peuvent utiliser https://api.olabassist.com/mcp/olab_YOUR_KEY. Traitez cette URL comme un mot de passe et utilisez une clé distincte pour elle, afin de pouvoir la révoquer séparément.

Exemples de questions : « Quels sites de mes clients ont perdu des points cette semaine ? », « Qui ChatGPT recommande-t-il à la place d’example.com ? », « Quels sont les problèmes critiques sur example.com, avec le correctif de chacun ? »

Looker Studio (Data Studio)

Le connecteur OLAB Assist pour Looker Studio lit la même API v1. Sur la page Intégrations, créez une clé, choisissez Connecter dans Looker Studio, autorisez l’accès et collez la clé. Les données sont lues à l’ouverture du rapport et conservées pendant la durée de fraîcheur des données de la source (12 heures par défaut ; choisissez 15 minutes ou 1 heure pour des mises à jour plus rapides). En 2026, Google a renommé Looker Studio en Data Studio ; c’est le même produit.

Choisissez une table par source de données et filtrez sur un site ou sur tous les sites. Combinez les sources de données dans un rapport grâce au champ Site. Chaque table s’ouvre avec un graphique par défaut adapté.

  • Score history (par défaut : score GEO dans le temps) : une ligne par audit avec Scan date, Site, Report et tous les scores et nombres de problèmes. Suit la période du rapport.
  • AI visibility vs competitors (par défaut : nombre de mentions par marque) : une ligne par marque suivie dans chaque réponse IA, avec Asked on, Site, Brand, Own brand, Assistant, Question, Intent et les métriques Times named, Times cited et Rank. Affichez-la dans le temps par Brand pour vous comparer à vos concurrents.
  • Issue trend by category (par défaut : problèmes critiques dans le temps) : une ligne par audit et par catégorie (SEO, GEO, AEO, AIO) avec Critical issues, Warnings, Open issues et le score de la catégorie.
  • Sites : Site, Brand name, Last checked, Report, Score, SEO/GEO/AEO/AIO score, Critical issues, Warnings, AI answers checked, AI answers naming the brand, AI named rate, AI rank among tracked brands.
  • Open issues : Site, Issue, Status, Category, Impact, Evidence, How to fix, Where, Check ID et un décompte Issues.
  • AI answers : une ligne par réponse avec Asked on, Site, Question, Intent, Assistant, Named, Cited as source, Sentiment, Brands named et les métriques Answers, Answers naming the brand, Answers citing the site et Rank when named. Suit la période du rapport.

Un bon point de départ : une série temporelle de Score à partir de Score history, et un tableau de Answers naming the brand ÷ Answers par Assistant à partir de AI answers.

Notion

Aucun code n’est nécessaire. Sur la page Intégrations, choisissez Connecter Notion. Sur l’écran d’autorisation de Notion, dupliquez le modèle AI Visibility Dashboard (un clic, rien d’autre à choisir) ou partagez une page, puis sélectionnez-la. Vous obtenez une page de tableau de bord à votre marque avec un résumé par site et trois bases de données affichées dans la page, mises à jour après chaque audit et chaque nouvelle réponse IA (au plus tard environ une heure après, ou immédiatement avec Synchroniser) :

  • Sites : une ligne par site avec le score global et les scores SEO, GEO, AEO, AIO, les problèmes critiques et les avertissements, la fréquence à laquelle les réponses IA vous mentionnent, votre rang parmi les marques suivies, les dates et les liens vers le rapport et le tableau de bord.
  • Issues : les problèmes ouverts avec leur statut, leur catégorie, leur impact, leur preuve et la façon de les corriger. Les problèmes corrigés sont marqués Resolved au lieu d’être supprimés.
  • AI answers (l’historique des prompts IA) : une ligne par réponse à partir des 30 derniers jours, avec la question, son intention, l’assistant, si vous avez été mentionné, le rang, la citation comme source, le sentiment, les marques mentionnées et les sources.

Les lignes sont mises à jour sur place, jamais dupliquées. Vous pouvez ajouter vos propres colonnes et vues ; nos colonnes sont écrasées à chaque synchronisation. Les nouvelles colonnes que nous ajouterons apparaîtront automatiquement dans vos bases de données existantes. La déconnexion arrête les mises à jour et laisse les pages dans Notion.

Intention et sentiment

Chaque question suivie reçoit une étiquette d’intention : research, comparison, purchase ou brand, attribuée une fois par un petit modèle de langage (avec un repli sur des mots-clés). Lorsqu’une réponse mentionne votre marque, son ton est étiqueté positive, neutral ou negative. Les deux figurent dans l’API (questions[].intent, answers[].question.intent, answers[].sentiment, ai_visibility.by_intent), dans Notion et dans Looker Studio, et le tableau de bord permet de filtrer les réponses selon ces étiquettes.

Gestion des versions

Ceci est la version 1. Dans la v1, nous ne faisons qu’ajouter : de nouveaux endpoints, de nouveaux champs et de nouveaux types d’événements. Nous ne supprimons ni ne renommons de champs, et nous ne modifions ni leur signification ni leur type. Ignorez les champs que vous ne connaissez pas et votre intégration continuera de fonctionner à mesure que nous ajoutons des fonctionnalités. Si une modification incompatible devient un jour nécessaire, elle sera publiée sous /api/v2, à côté de la v1, et la v1 continuera de fonctionner pendant une période de transition annoncée par e-mail.

Historique des modifications

  • 2026-10 : publication de la v1 : API REST, webhooks (scan.completed, answers.updated, site.created, site.deleted), serveur MCP et synchronisation Notion.
  • 2026-10 : alertes (score.dropped, visibility.lost, visibility.gained), formats Slack et Discord, modèle de tableau de bord Notion, tables Looker Studio des concurrents et des catégories, intention des questions.
  • 2026-10 : GET /sites/{site}/tasks et l’outil MCP get_tasks : les problèmes ouverts sous forme de tâches Markdown pour les agents de code IA.