OLAB Assist Anmelden
Entwickler

API, Webhooks und MCP

Bring deine Monitoring-Daten aus OLAB Assist in die Tools, die deine Agentur schon nutzt. Version 1, nur Lesezugriff, im Agency-Paket enthalten.

Überblick

OLAB Assist bietet Agenturen fünf Wege, ihre Monitoring-Daten außerhalb des Dashboards zu nutzen. Alle lesen dieselben Daten und folgen demselben versionierten Vertrag, daher stimmt das, was du in einem siehst, mit den anderen überein.

  • REST-API: Hol dir Websites, Scores, Ergebnisse, KI-Antworten, Score-Verlauf, Trends und Änderungen in ein CRM, ein Data Warehouse oder ein Reporting-Tool.
  • Webhooks: Erhalte ein signiertes JSON-Event, sobald ein Scan abgeschlossen ist oder neue KI-Antworten eintreffen – kein Polling nötig.
  • MCP-Server: Verbinde Claude, ChatGPT, Cursor oder einen beliebigen Model-Context-Protocol-Client und frag in natürlicher Sprache nach deinen Websites.
  • Looker Studio: Erstelle mit dem OLAB Assist-Connector Kundenreports zu Scores, Problemen und KI-Sichtbarkeit.
  • Notion: Halte eine Notion-Seite mit deinen Websites, Problemen und KI-Antworten aktuell, ganz ohne Code.

Lieber Schritt für Schritt? Die Integrationsanleitungen führen dich durch die Einrichtung: Notion, Looker Studio, Slack, Discord, Zapier und Make, REST-API und MCP.

API, Webhooks, Looker Studio und Notion sind im Paket Agency enthalten. Der MCP-Server ist ab Founders & Makers enthalten: mit Lesezugriff in Founders & Makers und Growth, in Agency zusätzlich mit Tools, die Aktionen ausführen. Der Account-Inhaber verwaltet Schlüssel und Webhooks unter Integrationen.

Authentifizierung

Erstelle einen Schlüssel auf der Seite Integrationen. Der vollständige Schlüssel wird nur einmal angezeigt; wir speichern nur einen Hash davon. Sende ihn mit jeder Anfrage:

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

Schlüssel haben nur Lesezugriff und sind auf deinen Workspace beschränkt: Ein Schlüssel sieht immer nur die Websites des Accounts, der ihn erstellt hat. Widerrufst du einen Schlüssel auf der Seite „Integrationen“, funktioniert er sofort nicht mehr. Verlässt der Account das Paket Agency, funktionieren seine Schlüssel erst wieder, wenn er zurückkehrt.

Anfragen und Limits

  • Basis-URL: https://api.olabassist.com/api/v1. GET /api/v1 gibt die Liste der Endpunkte zurück.
  • Alle Endpunkte verwenden GET und geben JSON zurück: { "data": …, "api_version": "v1" }. Paginierte Listen geben zusätzlich next_cursor zurück.
  • Zeitstempel sind ISO 8601 in UTC. Scores reichen von 0 bis 100.
  • Rate-Limit: 120 Anfragen pro Minute und Schlüssel. Darüber erhältst du 429 mit retryAfterSeconds.
  • Überall, wo ein Pfad {site} enthält, kannst du die Website-ID oder ihre Domain übergeben, z. B. /sites/example.com.

Endpunkte

GET /account

Dein Paket, Limits und Nutzung.

GET /sites

Jede überwachte Website mit ihrem neuesten Score und ihren offenen Problemen.

{
  "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}

Alles oben Genannte plus ai_visibility (geprüfte Antworten, wie viele dich genannt haben, wie viele deine Website zitiert haben, dein Rang unter den getrackten Marken, Sentiment), share_of_voice pro getrackter Marke, top_sources, die die Assistenten zitieren, competitors, questions und engines.

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

Checks aus dem neuesten Scan mit Beleg und Fix (summary, where und, falls vorhanden, einfügefertiger code). Ohne status werden alle Checks zurückgegeben.

GET /sites/{site}/tasks

Offene Probleme aus dem neuesten Scan als Aufgaben für einen KI-Coding-Agenten (Claude Code, Cursor o. Ä.), in Markdown: Kontext, Schritte, Code, wie jeder Platzhalter anhand der Website selbst ausgefüllt wird, wann die Aufgabe erledigt ist und was nicht angefasst werden darf. Gibt { "data": { "markdown": "…", "tasks": 5 } } zurück. Parameter: finding (eine Check-ID aus /findings, für eine einzelne Aufgabe) und lang (en, tr, es, de oder fr). Ein bestandener Check gibt 404 NO_TASK zurück.

GET /sites/{site}/answers

Gespeicherte KI-Antworten, die neuesten zuerst. Jede Antwort enthält die Frage, den Assistenten (engine), ob deine Marke genannt (named) und zitiert (cited) wurde, ihren Rang (rank), das sentiment, jede getrackte Marke in der Antwort und die zitierten Quellen.

Parameter: engine, question_id, since (ISO-Datum), limit (1–500, Standard 100), cursor, include_answer=true für den vollständigen Antworttext. Ist next_cursor nicht null, übergib den Wert als cursor, um die nächste Seite zu erhalten.

GET /sites/{site}/history

Score nach jedem Scan, die ältesten zuerst (limit bis 200).

GET /sites/{site}/trends

Zeitreihen für Diagramme und Reports, gruppiert nach day, week (Montag) oder month (UTC). Parameter: from und to (YYYY-MM-DD, einschließlich; Standard sind die letzten 90 Tage, maximal zwei Jahre), bucket (Standard hängt vom Zeitraum ab). Die Antwort enthält periods (Startdaten der Perioden), series (ein Array pro Kennzahl, ausgerichtet an periods, null, wo keine Daten vorliegen), einen catalog, der jede Reihe beschreibt (unit: score, pct, count oder rank; better: up oder down), sowie die changes im Zeitraum.

Reihen: score.overall, score.seo, score.geo, score.aeo, score.aio (letzter Scan jeder Periode), issues.fail, issues.warn, ai.visibility, ai.cited, ai.positive, ai.negative (Prozentwerte), ai.position (durchschnittlicher Rang, wenn genannt), ai.answers, engine.<assistant> und intent.<intent> (Sichtbarkeit in %) sowie brand.<competitor domain> (Anteil der Antworten, die diesen Wettbewerber nennen).

GET /sites/{site}/changes

Was sich zwischen Scans geändert hat: neue Probleme (new), Verschlechterungen (worse) und Verbesserungen (better, behoben). Parameter: since, limit.

Fehler

Fehler verwenden HTTP-Statuscodes und einen JSON-Body: { "error": "NOT_FOUND", "message": "…" }.

  • 401 Schlüssel fehlt, ist ungültig oder widerrufen
  • 403 API_NOT_IN_PLAN der Workspace ist nicht im Paket Agency
  • 404 die Website ist nicht in diesem Workspace
  • 405 die API ist schreibgeschützt
  • 429 Rate-Limit erreicht

Webhooks

Füge auf der Seite „Integrationen“ eine https-Adresse hinzu und wähle die Events, die du erhalten willst. Jedes Event wird als POST mit einem JSON-Body gesendet:

{
  "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/…"
  }
}

Events

  • score.dropped: Der Gesamt-Score ist mindestens um den Schwellenwert des Webhooks gefallen (standardmäßig 10 %, 1–90 % pro Webhook). Vorheriger und neuer Score, der Rückgang in Punkten und Prozent sowie die Veränderung jeder Kategorie.
  • visibility.lost: Ein KI-Assistent hat deine Marke in seiner letzten Antwort auf eine getrackte Frage genannt und tut es jetzt nicht mehr. Enthält den Assistenten, die Frage und named_instead, die Wettbewerber, die er stattdessen empfiehlt.
  • visibility.gained: Ein Assistent nennt deine Marke jetzt und hat es vorher nicht getan, mit ihrem Rang.
  • scan.completed: Ein Scan ist abgeschlossen (täglich, manuell oder als erneute Prüfung). Scores, Anzahl der Probleme und was sich geändert hat.
  • answers.updated: Neue KI-Antworten für eine getrackte Frage, ein Eintrag pro Assistent, im selben Format wie /answers.
  • site.created und site.deleted.

Nutze Test senden auf der Seite „Integrationen“, um ein ping-Event zu erhalten.

Slack, Discord, Asana, ClickUp

Jeder Webhook hat ein Nachrichtenformat. Füge die Adresse eines eingehenden Webhooks von Slack oder Discord ein, und OLAB Assist sendet eine lesbare, einzeilige Benachrichtigung mit Link in der Sprache des Accounts (Slack- und Discord-Adressen werden automatisch erkannt). Für Asana, ClickUp, Trello, HubSpot und andere nutzt du das JSON-Format mit Zapier, Make oder n8n: Ein Trigger „Catch webhook“, gefolgt von „Create task“, macht aus jedem score.dropped oder visibility.lost eine Aufgabe. Jede Zustellung enthält OLAB-Signature; Slack und Discord ignorieren den Header einfach.

Signatur prüfen

Jede Anfrage enthält OLAB-Event, OLAB-Delivery und OLAB-Signature: t=<unix seconds>,v1=<hex>. Die Signatur ist ein HMAC-SHA256 von t + "." + raw body mit dem Signatur-Secret deines Webhooks. Vergleiche sie in konstanter Zeit und lehne alte Zeitstempel ab:

// 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"])

Neuversuche

Antworte innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Alles andere wird nach etwa 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 24 Stunden erneut versucht. Nach 25 fehlgeschlagenen Zustellungen in Folge wird der Webhook pausiert; aktiviere ihn auf der Seite „Integrationen“ wieder. Nutze id, um ein bereits verarbeitetes Event zu ignorieren.

MCP-Server

Der MCP-Endpunkt ist https://api.olabassist.com/mcp (Streamable HTTP). Er stellt die API-Endpunkte als Tools mit Lesezugriff bereit: list_sites, get_site, get_findings, get_tasks, get_ai_answers, get_score_history, get_trends, get_changes. Im Paket Agency bietet der Server außerdem vier Tools, die Aktionen ausführen, mit denselben Limits wie im Dashboard: add_question (eine neue Frage tracken; alle Assistenten beantworten sie sofort), start_scan (eine Website jetzt scannen; zählt zu den manuellen Scans pro Tag deines Pakets), mark_task_applied (übergib die Aufgabe so, wie get_tasks sie benennt; die nächsten Scans zeigen vorher und nachher) und add_competitor. In Founders & Makers und Growth werden diese Tools nicht aufgeführt.

Clients, die Header akzeptieren (Claude Code, Cursor und andere):

{
  "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"

Clients, die nur eine URL annehmen, können https://api.olabassist.com/mcp/olab_YOUR_KEY verwenden. Behandle diese URL wie ein Passwort und nutze dafür einen eigenen Schlüssel, damit du ihn separat widerrufen kannst.

Beispielfragen: „Welche Websites meiner Kunden haben diese Woche Punkte verloren?“, „Wen empfiehlt ChatGPT statt example.com?“, „Liste die kritischen Probleme auf example.com mit dem jeweiligen Fix auf.“

Looker Studio (Data Studio)

Der OLAB Assist-Connector für Looker Studio liest dieselbe v1-API. Erstelle auf der Seite „Integrationen“ einen Schlüssel, wähle In Looker Studio verbinden, erlaube den Zugriff und füge den Schlüssel ein. Die Daten werden beim Öffnen des Reports gelesen und für die Datenaktualität der Datenquelle vorgehalten (standardmäßig 12 Stunden; wähle 15 Minuten oder 1 Stunde für schnellere Aktualisierungen). Google hat Looker Studio 2026 in Data Studio umbenannt; es ist dasselbe Produkt.

Wähle eine Tabelle pro Datenquelle und filtere nach einer oder allen Websites. Kombiniere Datenquellen in einem Report über das Feld Site. Jede Tabelle öffnet sich mit einem sinnvollen Standarddiagramm.

  • Score history (Standard: GEO-Score im Zeitverlauf): eine Zeile pro Scan mit Scan date, Site, Report sowie allen Scores und Problemzahlen. Folgt dem Zeitraum des Reports.
  • AI visibility vs competitors (Standard: Nennungen nach Marke): eine Zeile pro getrackter Marke in jeder KI-Antwort, mit Asked on, Site, Brand, Own brand, Assistant, Question, Intent und den Kennzahlen Times named, Times cited und Rank. Stell sie im Zeitverlauf nach Brand dar, um dich mit Wettbewerbern zu vergleichen.
  • Issue trend by category (Standard: kritische Probleme im Zeitverlauf): eine Zeile pro Scan und Kategorie (SEO, GEO, AEO, AIO) mit Critical issues, Warnings, Open issues und dem Kategorie-Score.
  • 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 und eine Kennzahl Issues.
  • AI answers: eine Zeile pro Antwort mit Asked on, Site, Question, Intent, Assistant, Named, Cited as source, Sentiment, Brands named und den Kennzahlen Answers, Answers naming the brand, Answers citing the site und Rank when named. Folgt dem Zeitraum des Reports.

Ein guter Einstieg: eine Zeitreihe von Score aus Score history und eine Tabelle von Answers naming the brand ÷ Answers nach Assistant aus AI answers.

Notion

Kein Code nötig. Wähle auf der Seite „Integrationen“ Notion verbinden. Dupliziere auf dem Freigabebildschirm von Notion entweder die Vorlage AI Visibility Dashboard (ein Klick, sonst nichts auszuwählen) oder gib eine Seite frei und wähle sie anschließend aus. Du erhältst eine Dashboard-Seite in deinem Branding mit einer Zusammenfassung pro Website und drei eingebetteten Datenbanken, die nach jedem Scan und jeder neuen KI-Antwort aktualisiert werden (spätestens nach etwa einer Stunde oder sofort mit Sync starten):

  • Sites: eine Zeile pro Website mit Gesamt-Score sowie SEO-, GEO-, AEO- und AIO-Score, kritischen Problemen und Warnungen, wie oft KI-Antworten dich nennen, deinem Rang unter den getrackten Marken, Datumsangaben und Links zu Report und Dashboard.
  • Issues: offene Ergebnisse mit Status, Kategorie, Auswirkung, Beleg und Fix. Behobene Probleme werden als Resolved markiert statt gelöscht.
  • AI answers (das Prompt-Log): eine Zeile pro Antwort ab den letzten 30 Tagen, mit Frage, Intention, Assistent, ob du genannt wurdest, Rang, Zitierung, Sentiment, den genannten Marken und den Quellen.

Zeilen werden direkt aktualisiert, nie dupliziert. Du kannst eigene Spalten und Ansichten hinzufügen; unsere Spalten werden bei jedem Sync überschrieben. Neue Spalten, die wir später hinzufügen, erscheinen automatisch in deinen bestehenden Datenbanken. Trennst du die Verbindung, stoppen die Updates und die Seiten bleiben in Notion.

Intention und Sentiment

Jede getrackte Frage erhält ein Intention-Label: research, comparison, purchase oder brand, einmalig vergeben von einem kleinen Sprachmodell (mit Keyword-Fallback). Nennt eine Antwort deine Marke, wird ihr Ton als positive, neutral oder negative eingestuft. Beides erscheint in der API (questions[].intent, answers[].question.intent, answers[].sentiment, ai_visibility.by_intent), in Notion und in Looker Studio, und im Dashboard kannst du Antworten danach filtern.

Versionierung

Dies ist Version 1. Innerhalb von v1 fügen wir nur hinzu: neue Endpunkte, neue Felder und neue Event-Typen. Wir entfernen oder benennen keine Felder um, ändern weder ihre Bedeutung noch ihre Typen. Ignoriere Felder, die du nicht kennst, dann funktioniert deine Integration weiter, während wir Funktionen ergänzen. Sollte jemals eine inkompatible Änderung nötig sein, erscheint sie als /api/v2 neben v1, und v1 läuft für eine per E-Mail angekündigte Übergangszeit weiter.

Changelog

  • 2026-10: v1 veröffentlicht: REST-API, Webhooks (scan.completed, answers.updated, site.created, site.deleted), der MCP-Server und der Notion-Sync.
  • 2026-10: Benachrichtigungen (score.dropped, visibility.lost, visibility.gained), Formate für Slack und Discord, die Notion-Dashboard-Vorlage, Looker-Studio-Tabellen für Wettbewerber und Kategorien, Intention von Fragen.
  • 2026-10: GET /sites/{site}/tasks und das MCP-Tool get_tasks: offene Probleme als Markdown-Aufgaben für KI-Coding-Agenten.