API-Referenz

Basis-URL: https://api.analytics.house (oder Ihr eigener Worker, wenn Sie selbst hosten). Antworten sind JSON. Authentifizierte Endpunkte benötigen Authorization: Bearer <token> von /auth/login.

Ereignisse senden: POST /collect

Öffentlich (kein Token). Gibt sofort 202 zurück; Ereignisse werden im Hintergrund geschrieben.

curl -X POST https://api.analytics.house/collect \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_PROJECT_KEY",
    "events": [
      { "event_name": "pageview", "event_type": "pageview", "path": "/pricing", "session_id": "s1" },
      { "event_name": "signup", "event_type": "custom", "properties": { "plan": "pro" } }
    ]
  }'

Ereignisfelder: event_name (Pflichtfeld), event_type, path, referrer, session_id, user_id, timestamp (ISO 8601), utm_source, utm_medium, utm_campaign, properties (Objekt). Bots werden ignoriert. Bei Überschreitung des Rate-Limits erhalten Sie 429 mit Retry-After. Wenn das Projekt erlaubte Websites festlegt, erhalten Browser-Anfragen von allen anderen Websites 403. Ereignisse desselben Besuchers mit höchstens 30 Minuten Abstand bilden einen Besuch, und die UTM-Tags der Einstiegsseite werden auf den Rest des Besuchs übertragen. session_id wird ignoriert, es sei denn, das Projekt schaltet den strikten Modus ab, und user_id wird immer als täglicher Hash gespeichert.

Konto

• POST /auth/register: { "email", "password" }
• POST /auth/login: gibt { "token", "user", "expires_at" } zurück
• GET /auth/me: gibt das aktuelle Kontoprofil zurück
• PUT /auth/me: { "email", "current_password" } ändert die E-Mail-Adresse des Kontos und gibt ein neues Token zurück
• POST /auth/change-password: { "current_password", "new_password" }
• DELETE /auth/me: { "password", "code" } löscht das Konto und alle eigenen Projekte endgültig (code nur bei aktivierter 2FA)
• POST /auth/forgot-password: { "email" } sendet per E-Mail einen einmalig gültigen Link zum Zurücksetzen. Die Antwort ist dieselbe, egal ob das Konto existiert oder nicht.
• POST /auth/reset-password: { "token", "password" }
• POST /auth/logout: Sitzungen sind zustandslose Tokens, daher verwirft der Client einfach sein Token.
• POST /auth/verify-email: { "token" } aus dem Link in der Bestätigungs-E-Mail (keine Sitzung nötig). POST /auth/verify-email/resend sendet einen neuen Link. Neue Konten und geänderte Adressen sind zunächst unbestätigt; Einladungen, Berichte und Benachrichtigungs-E-Mails gehen nur an bestätigte Adressen.

Zwei-Faktor-Authentifizierung (TOTP)

• POST /auth/2fa/setup: { "password" } gibt ein Secret und eine otpauth://-URI für Ihre Authenticator-App zurück.
• POST /auth/2fa/enable: { "code" } bestätigt den ersten Code und gibt einmalig gültige Wiederherstellungscodes zurück (werden nur einmal angezeigt).
• POST /auth/2fa/disable: { "password", "code" }
• Bei aktivierter 2FA gibt POST /auth/login { "two_factor_required": true, "challenge_token" } zurück. Schließen Sie die Anmeldung innerhalb von 5 Minuten mit POST /auth/2fa/verify und { "challenge_token", "code" } ab (ein 6-stelliger Code oder ein Wiederherstellungscode).

Projekte

• GET /projects, POST /projects ({ "name" })
• GET | PUT | DELETE /projects/:id. settings-Schlüssel: strict_privacy, geo_detail, ephemeral_raw, ai_assistant, respect_dnt (true/false), k_anonymity (0 bis 100), allowed_hostnames (Liste; *.example.com umfasst Subdomains). Neue Projekte starten mit strict_privacy: true, geo_detail: false, k_anonymity: 5.

Daten abrufen

• GET /projects/:id/stats?start=ISO&end=ISO: Summen, Zeitreihen und Aufschlüsselungen (standardmäßig die letzten 7 Tage, maximal 366), darunter Quellen (Seitenaufrufe ohne verweisende Seite sind (direct)), UTM-Quelle/-Medium/-Kampagne sowie Einstiegs- und Ausstiegsseiten. Mit compare=1 erhalten Sie unter previous zusätzlich den vorherigen, gleich langen Zeitraum. Jedes benutzerdefinierte Ereignis enthält eine conversion_rate (Anteil der Besucher in Prozent, die es ausgelöst haben).
• Filter: Fügen Sie einen oder mehrere Parameter f=dimension:value hinzu, zum Beispiel f=country:DE&f=path:/pricing. Dimensionen: path, referrer ((direct) für Aufrufe ohne verweisende Seite), country, region, city, browser, device, os, utm_source, utm_medium, utm_campaign, event. Bis zu 5 Filter; gefilterte Abfragen lesen Rohereignisse, daher ist der Zeitraum auf 92 Tage begrenzt.
• GET /projects/:id/props?event=Outbound%20Link&key=url: die häufigsten Werte einer Ereigniseigenschaft (bis zu 20, höchstens 92 Tage).
• GET /projects/:id/events?limit=100&offset=0: einzelne Ereignisse, neueste zuerst (limit bis 500). Nur für Inhaber und Administratoren; Betrachter und Statistikschlüssel erhalten nur aggregierte Werte.
• GET /projects/:id/realtime: Besucher der letzten 5 Minuten und Seiten der letzten 30 Minuten.

Statistiken werden etwa 30 Sekunden lang zwischengespeichert. Wie Besucher gezählt werden, erfahren Sie unter Datenschutz & Daten.

Trichter

Ein Trichter besteht aus 2 bis 6 geordneten Schritten. Jeder Schritt ist { "type": "page", "value": "/pricing" } (beenden Sie den Wert mit * für einen Präfix-Abgleich) oder { "type": "event", "value": "signup" }. Schritte werden pro Sitzung (ein Browser-Tab) in ihrer Reihenfolge gezählt.

• GET /projects/:id/funnels, POST /projects/:id/funnels ({ "name", "steps" })
• GET /projects/:id/funnels/:funnelId?start=ISO&end=ISO: Anzahl pro Schritt, Conversion gegenüber dem vorherigen Schritt, Gesamt-Conversion, Abbrüche.
• DELETE /projects/:id/funnels/:funnelId

Öffentliche Freigabelinks

• POST /projects/:id/share erstellt ein Token für einen schreibgeschützten Link (oder gibt das vorhandene zurück); DELETE /projects/:id/share widerruft es.
• GET /public/:token, /public/:token/stats, /public/:token/props: dieselben Parameter wie oben, ohne Authentifizierung. Enthält nie Ihren API-Schlüssel oder Rohereignisse.

CSV-Export

• GET /projects/:id/export?start=ISO&end=ISO: die Zahlen hinter dem Dashboard (Zusammenfassung, Zeitreihen, Aufschlüsselungen).
• GET /projects/:id/export?what=events&start=ISO&end=ISO: Rohereignisse, bis zu 20.000 Zeilen, höchstens 92 Tage.

Umsatz und Scrolltiefe

• Senden Sie Umsatz als properties.revenue (Zahl) und optional properties.currency (ISO 4217, Standard USD) mit einem benutzerdefinierten Ereignis.
• GET /projects/:id/revenue: Summen, Anzahl der Bestellungen, durchschnittlicher Bestellwert und Umsatz pro Besucher, gruppiert nach Währung (nie über Währungen hinweg summiert).
• GET /projects/:id/scroll: Messwerte zur Scrolltiefe (der Tracker benötigt data-scroll="true"). Diese Messwerte zählen nicht als Ereignisse, Sitzungen oder Absprünge.

Team, Statistik-API-Schlüssel, Berichte, Import

• GET/POST /projects/:id/members, DELETE /projects/:id/members/:userId, DELETE /projects/:id/invites?email=. Rollen: Betrachter (lesen) und Administrator (verwalten). Nur der Inhaber verwaltet das Team.
• POST /projects/:id/keys gibt einen schreibgeschützten Statistikschlüssel (ea_sk_...) einmalig zurück. Verwenden Sie ihn als Authorization: Bearer für stats, props, realtime, revenue, scroll und funnels. Rohereignisse und der Ingest-Schlüssel werden nie offengelegt. Widerrufen mit DELETE /projects/:id/keys/:id.
• GET/PUT /projects/:id/reports (frequency: off | weekly | monthly). POST /projects/:id/reports/test sendet eine Vorschau an die E-Mail-Adresse Ihres Kontos (3 pro Stunde). E-Mails werden über Cloudflare Email Service versendet.
• POST /projects/:id/import mit { "csv": "date,visitors,..." }: Tagessummen aus Plausible, Simple Analytics und ähnlichen Tools. Tage, die sich mit bereits erfassten Tagen überschneiden, werden abgelehnt. DELETE entfernt den Import.

Datenschutz-Manifest & First-Party-Worker-Proxy

• GET /projects/:id/privacy: gibt den aktuellen Stand der kryptografischen Salt-Rotation zurück, den Subresource-Integrity-Hash (sha384) für /tracker.js, die aktiven Datenschutz-Flags (strict_privacy, ephemeral_raw, k_anonymity) und ein sofort einsetzbares Proxy-Skript für einen First-Party-Cloudflare-Worker.
• GET /public/:token/privacy: öffentliches, schreibgeschütztes Manifest zur Datenschutzprüfung für geteilte Dashboards.

KI-Such-Attribution, Core Web Vitals, Bot-Schutz, Anmerkungen & Webhooks

• GET /projects/:id/stats enthält ai_sources (ChatGPT, Perplexity, Claude, Gemini, Copilot, DeepSeek usw.), channels (7 automatische Akquisitionskanäle) und anomalies (Erkennung von Traffic-Spitzen und -Einbrüchen per z-Score).
• GET /projects/:id/vitals?start=ISO&end=ISO: gibt score (Real Experience Score von 0–100), metrics (p50/p75/p95 sowie Anteile „Gut“/„Schlecht“ für LCP, INP, CLS, TTFB, FCP) und eine Aufschlüsselung der Latenz pro Route zurück.
• GET /projects/:id/bots?start=ISO&end=ISO: gibt datenschutzfreundliche Tageszahlen zu KI-Trainings-Crawlern (GPTBot, ClaudeBot, Google-Extended), KI-Suchassistenten (PerplexityBot, OAI-SearchBot) und Suchbots (Googlebot) zurück.
• GET | POST /projects/:id/annotations und DELETE /projects/:id/annotations/:annId: Produktstarts und Marketing-Meilensteine an UTC-Daten auf der Zeitachse markieren.
• GET | POST /projects/:id/alerts, DELETE /projects/:id/alerts/:webhookId und POST /projects/:id/alerts/:webhookId/test: Benachrichtigungen per Slack, Discord, HTTPS (mit SSRF-Schutz) und E-Mail für Traffic-Spitzen, Traffic-Einbrüche und Änderungen bei Zielen einrichten. GET /projects/:id/alerts/log listet gesendete Benachrichtigungen auf.
• GET /public/:token/badge.svg?metric=visitors|pageviews&period=24h|7d|30d&style=emerald|blue|slate: einbettbares Live-SVG-Badge mit Traffic-Zahlen für GitHub-READMEs und Fußzeilen.

Fragen an Ihre Analysedaten und JavaScript-Fehler

• POST /projects/:id/ask mit { "question": "Which pages grew this month?" }: Antworten in verständlicher Sprache, nur auf Basis aggregierter Zahlen (Rohereignisse und Besucher-IDs erreichen die KI nie). Bis zu 10 Fragen pro Minute und Nutzer.
• GET /projects/:id/errors?start=ISO&end=ISO: JavaScript-Fehler, gruppiert nach Meldung, Datei und Zeile. Der Tracker sendet sie nur mit data-errors="true"; sie zählen nie als Traffic.

Klickkarten und Pfade

• GET /projects/:id/clicks?start=ISO&end=ISO: Seiten mit Klickdaten. Fügen Sie path=/pricing hinzu, um die Elemente dieser Seite zu erhalten (Klicks, Wutklicks und Klicks ohne Wirkung, Anteil); fügen Sie selector=... hinzu, um das 10×10-Raster der Klickpositionen zu erhalten. Elemente mit weniger Klicks als der k-Anonymitäts-Schwellenwert des Projekts werden ausgeblendet.
• GET /projects/:id/journeys?path=/pricing&start=ISO&end=ISO: Seiten, die innerhalb eines Besuchs direkt davor und danach aufgerufen wurden; Schritte, die weniger Besuche als der Schwellenwert genommen haben, werden unter „Other“ zusammengefasst. Liest einzelne Ereignisse, daher ist der Zeitraum auf 92 Tage begrenzt.
• GET /projects/:id/errors markiert jeden Fehlertyp, der im Zeitraum zum ersten Mal aufgetreten ist, mit is_new; Benachrichtigungen können bei new_error ausgelöst werden.

Status

GET /public/status ist öffentlich. Der Status wird selbst überwacht (eine Prüfung alle 15 Minuten) und ist kein SLA.