API-Endpunkte

Zenovay stellt mehrere API-Endpunkt-Gruppen für den programmgesteuerten Zugriff auf Ihre Analysedaten zur Verfügung.

Authentifizierung

Alle API-Anfragen erfordern Authentifizierung. Die Methode hängt davon ab, welche API Sie verwenden:

Weitere Details zur API-Schlüsselverwaltung finden Sie unter Authentifizierung.

Externe API

Basis-URL: https://api.zenovay.com/api/external/v1

Server-seitige API für den Zugriff auf Analysedaten mit API-Schlüssel-Authentifizierung (X-API-Key-Header).

Verfügbare Endpunkte

Jeder Endpunkt verfügt über eine dedizierte Referenzseite mit Parametern, Response-Schemata, TypeScript-Schnittstellen und Code-Beispielen in cURL, JavaScript, Python und TypeScript.

Siehe auch Externe-API-Übersicht für eine grundlegende Einführung.

Einbettbare Widgets

Basis-URL: https://api.zenovay.com/widgets

Vorgefertigte Widgets, die keine Authentifizierung erfordern. Verwenden Sie Ihren Tracking-Code zur Identifizierung der Website.

Weitere Informationen finden Sie unter Widgets.

Echtzeit-Daten

Basis-URL: https://api.zenovay.com/e

Öffentliche JSON-Endpunkte für Live-Statistiken. Keine Authentifizierung erforderlich.

Weitere Informationen finden Sie unter Echtzeit-Daten.

Ratenlimits

API-Ratenlimits variieren je nach Plan:

Ratelimit-Header sind in allen Responses enthalten:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1642771200

Der Wert X-RateLimit-Limit spiegelt das Limit pro Minute Ihres Plans wider (z. B. 10 für Free, 30 für Pro, 60 für Scale, 120 für Enterprise).

Weitere Informationen finden Sie unter Ratenlimits.

Fehlercodes

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

{
"success": false,
"error": {
  "message": "The provided API key is missing or invalid",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

Webhooks

Richten Sie Webhooks ein, um Echtzeit-Benachrichtigungen zu erhalten:

Verfügbare Ereignisse

• visitor.identified - Wenn ein Besucher identifiziert wird
• visitor.high_value - Wenn die Besucherpunktzahl 80+ erreicht
• event.tracked - Wenn ein Ereignis nachverfolgt wird
• goal.completed - Wenn ein Ziel erreicht wird
• visitor.converted - Wenn ein Besucher konvertiert wird

Webhook-Payload

{
"event": "visitor.high_value",
"timestamp": "2025-01-20T15:30:00Z",
"data": {
  "visitor_id": "vis_abc123",
  "score": 92,
  "current_page": "/pricing",
  "time_on_site": 420
}
}

Dashboard-API-Übersicht

Die folgenden API-Gruppen unterstützen das Zenovay-Dashboard. Alle Endpunkte erfordern ein Bearer-JWT-Token im Header Authorization. Responses verwenden ein Standardformat:

{ "success": true, "data": { ... }, "timestamp": "..." }

Rollenbasierte Berechtigungen

Website-Settings-Endpunkte erzwingen rollenbasierten Zugriff. Rollen in Reihenfolge der Berechtigungsstufe:

Gespräche-API

Basis-URL: https://api.zenovay.com/api/conversations

Auth: Bearer JWT erforderlich. Teamzugehörigkeit wird für alle Anfragen überprüft.

CRUD-Vorgänge für KI-gestützte Gespräche innerhalb von Teams. Der Query-Parameter team_id wird standardmäßig auf die Organisation des authentifizierten Benutzers gesetzt, falls nicht angegeben.

Endpunkte

GET /conversations

Gibt Gespräche ohne Nachrichteninhalte zur Verbesserung der Leistung zurück.

Query-Parameter:

• team_id (optional) — wird standardmäßig auf die Organisation des Benutzers gesetzt

{
"success": true,
"data": [
  {
    "id": "uuid",
    "team_id": "uuid",
    "title": "Analytics Q3 review",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-07T14:30:00Z"
  }
]
}

GET /conversations/:id

Gibt das vollständige Gespräch einschließlich des Message-Arrays zurück.

{
"success": true,
"data": {
  "id": "uuid",
  "team_id": "uuid",
  "title": "Analytics Q3 review",
  "messages": [
    { "role": "user", "content": "Show top pages", "timestamp": "2026-02-07T14:30:00Z" },
    { "role": "assistant", "content": "Here are your top pages...", "timestamp": "2026-02-07T14:30:01Z" }
  ],
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:30:01Z"
}
}

POST /conversations

{
"title": "New conversation",
"team_id": "uuid"
}

• title (erforderlich) — nicht leerer String
• team_id (optional) — wird standardmäßig auf die Organisation des Benutzers gesetzt

Response: 201 mit dem erstellten Gespräch (enthält leeres messages: []).

PUT /conversations/:id

{
"title": "Updated title",
"messages": [...]
}

Beide Felder sind optional. Akzeptiert Teilaktualisierungen.

DELETE /conversations/:id

Response: 200 mit { "deleted": true }.

POST /conversations/:id/messages

Fügt eine Nachricht zum Gespräch hinzu. Der Server fügt jedem Nachricht einen timestamp hinzu.

{
"role": "user",
"content": "What were last week's top referrers?"
}

• role (erforderlich) — Nachrichtenrolle (z. B. "user", "assistant")
• content (erforderlich) — Nachrichtentext

Response: 201 mit dem vollständig aktualisierten Gespräch einschließlich aller Nachrichten.

Website-Einstellungen-API

Basis-URL: https://api.zenovay.com/api/websites

Auth: Bearer JWT erforderlich. Jeder Endpunkt erzwingt eine Mindestrolle.

Verwalten Sie die Website-Konfiguration einschließlich allgemeiner Einstellungen, Benachrichtigungen, Datenverkehrsausschlüsse, Umsatzverfolgung, Domänen und Teammitglieder. Alle Pfade werden durch :websiteId begrenzt.

Endpunkte

PUT /:websiteId/general

{
"domain": "example.com",
"name": "My Website",
"timezone": "America/New_York",
"primary_color": "#4F46E5",
"kpi_goal": 10000,
"public_dashboard": true,
"allowed_domains": ["example.com", "www.example.com"]
}

{
"success": true,
"data": {
  "id": "uuid",
  "domain": "example.com",
  "name": "My Website",
  "timezone": "America/New_York",
  "primary_color": "#4F46E5",
  "kpi_goal": 10000,
  "public_dashboard": true,
  "allowed_domains": ["example.com", "www.example.com"],
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/notifications

Gibt Benachrichtigungseinstellungen zurück. Falls keine festgelegt wurden, wird ein Standardobjekt mit nur dem website_id zurückgegeben.

PUT /:websiteId/notifications

Akzeptiert alle Benachrichtigungseinstellungsfelder. Verwendet ein Upsert-Muster: erstellt den Datensatz beim ersten Aufruf, aktualisiert ihn bei nachfolgenden Aufrufen.

GET /:websiteId/exclusions

Gibt sowohl IP- als auch Pfadausschlüsse in einer einzigen Response zurück.

{
"success": true,
"data": {
  "ip_exclusions": [
    { "id": "uuid", "website_id": "uuid", "ip_address": "192.168.1.1", "description": "Office IP", "created_at": "..." }
  ],
  "path_exclusions": [
    { "id": "uuid", "website_id": "uuid", "path_pattern": "/admin/*", "description": "Admin pages", "created_at": "..." }
  ]
}
}

POST /:websiteId/exclusions/ip

{
"ip_address": "192.168.1.1",
"description": "Office IP"
}

• ip_address (erforderlich)
• description (optional)

Response: 201. Gibt 409 zurück, wenn die IP bereits ausgeschlossen ist.

POST /:websiteId/exclusions/path

{
"path_pattern": "/admin/*",
"description": "Admin pages"
}

• path_pattern (erforderlich)
• description (optional)

Response: 201. Gibt 409 zurück, wenn das Pfadmuster bereits ausgeschlossen ist.

PUT /:websiteId/revenue

Erfordert die Rolle admin.

{
"revenue_provider": "stripe",
"revenue_currency": "USD"
}

{
"success": true,
"data": {
  "id": "uuid",
  "revenue_provider": "stripe",
  "revenue_currency": "USD",
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/domains

{
"success": true,
"data": {
  "primary_domain": "example.com",
  "allowed_domains": ["example.com", "www.example.com"],
  "verification_status": "verified"
}
}

PUT /:websiteId/domains

Erfordert die Rolle admin.

{
"domain": "example.com",
"allowed_domains": ["example.com", "www.example.com"]
}

allowed_domains muss ein Array sein, falls angegeben.

GET /:websiteId/team-members

Gibt Teammitglieder mit angereicherten Benutzerprofildaten zurück.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "deactivated_at": null,
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "avatar_url": "https://..."
    }
  }
]
}

POST /:websiteId/team-members

Laden Sie einen Benutzer per E-Mail ein. Erfordert die Rolle admin.

{
"email": "[email protected]",
"role": "editor"
}

• email (erforderlich) — muss ein registrierter Zenovay-Benutzer sein
• role (optional) — wird standardmäßig auf "viewer" gesetzt. Muss einer der folgenden sein: owner, admin, editor, viewer

Response: 201. Gibt 404 zurück, wenn die E-Mail nicht gefunden wird, 409 falls bereits Mitglied.

PUT /:websiteId/team-members/:memberId

Aktualisieren Sie die Rolle eines Mitglieds. Erfordert die Rolle admin.

{
"role": "admin"
}

• role (erforderlich) — muss einer der folgenden sein: owner, admin, editor, viewer

DELETE /:websiteId/team-members/:memberId

Entfernt ein Teammitglied (Soft-Delete). Erfordert die Rolle admin.

Response: 200 mit { "deleted": true }.

Onboarding-API

Basis-URL: https://api.zenovay.com/api/onboarding

Auth: Bearer JWT erforderlich. Benutzerbezogen (keine Team- oder Rollenprüfung).

Verfolgen Sie den Fortschritt des Benutzer-Onboardings. Jeder Benutzer hat einen einzigen Onboarding-Datensatz, der über Sitzungen hinweg erhalten bleibt.

Endpunkte

GET /onboarding/progress

Gibt den Onboarding-Status des Benutzers zurück. Falls kein Datensatz vorhanden ist, werden Standardwerte zurückgegeben.

{
"success": true,
"data": {
  "user_id": "uuid",
  "current_step": "add_website",
  "completed": false,
  "data": { "welcomed": true },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:00:00Z"
}
}

POST /onboarding/progress

Verwendet ein Upsert-Muster: erstellt den Datensatz beim ersten Aufruf, aktualisiert ihn bei nachfolgenden Aufrufen.

{
"step": "install_tracking",
"data": { "welcomed": true, "website_added": true },
"completed": false
}

• step — wird in der Datenbank als current_step gespeichert
• data — beliebiges JSON-Objekt zum Speichern des Schritt-spezifischen Zustands
• completed — wird standardmäßig auf false gesetzt

Teams-API

Basis-URL: https://api.zenovay.com/api/teams

Auth: Bearer JWT erforderlich. Teamzugehörigkeit wird überprüft (jedes aktive Mitglied kann auf alle zugreifen).

Schreibgeschützte Team-Kontext-Endpunkte für Berechtigungen, Nutzungsstatistiken und Mitgliederlisten. Verwenden Sie für Team-Management-Aktionen (Einladung, Rollenänderungen, Entfernung) die Endpunkte Website-Einstellungen-API für Teammitglieder.

Endpunkte

GET /teams/:id/permissions

Gibt die Rolle des authentifizierten Benutzers, den Plan des Teams, aktuelle Nutzungszahlen und berechnete Berechtigungsflags zurück.

{
"success": true,
"data": {
  "team_id": "uuid",
  "role": "admin",
  "plan": "Pro",
  "plan_limits": {
    "maxWebsites": 5,
    "maxTeamMembers": 5,
    "eventsPerMonth": 10000,
    "dataRetentionDays": 730
  },
  "current_usage": {
    "websites": 3,
    "team_members": 5
  },
  "permissions": {
    "can_manage_billing": false,
    "can_manage_team": true,
    "can_edit_settings": true,
    "can_view": true
  }
}
}

GET /teams/:id/usage

Gibt Nutzungsstatistiken für den aktuellen Abrechnungszeitraum zurück (Monat bis heute).

{
"success": true,
"data": {
  "team_id": "uuid",
  "plan": "Pro",
  "period": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-07T12:00:00.000Z"
  },
  "usage": {
    "events": 4521,
    "events_limit": 10000,
    "websites": 3,
    "websites_limit": 10,
    "team_members": 5,
    "team_members_limit": 10
  }
}
}

GET /teams/:id/members

Gibt Teammitglieder mit angereicherten Benutzerprofildaten zurück.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "name": "Jane",
      "avatar_url": "https://..."
    }
  }
]
}

Benutzerprofil-API

Basis-URL: https://api.zenovay.com/api/users

Auth: Bearer JWT erforderlich. Benutzerbezogen (nur eigenes Profil).

Verwalten Sie das Profil und die E-Mail-Adresse des authentifizierten Benutzers.

Endpunkte

PUT /users/me/email

Dedizierter Endpunkt für E-Mail-Änderungen mit SSO-Provider-Erkennung. Wenn sich der Benutzer über einen OAuth-Provider (Google, GitHub usw.) registriert hat, wird die Anfrage mit einer Nachricht abgelehnt, um die E-Mail stattdessen über diesen Provider zu aktualisieren.

{
"email": "[email protected]"
}

• email (erforderlich) — muss eine gültige E-Mail sein, die sich von der aktuellen unterscheidet

Response: 200 mit dem aktualisierten Benutzerdatensatz. Gibt 400 zurück, wenn der Benutzer ein SSO-Konto ist oder die E-Mail ungültig/unverändert ist.

Nächste Schritte

• Externe API - Server-seitige Analyse mit API-Schlüssel-Authentifizierung
• Widgets - Vorgefertigte einbettbare Widgets
• Echtzeit-Daten - Live-Besucherdaten-Endpunkte
• Authentifizierung - API-Schlüsselverwaltung
• Ratenlimits - Ratenlimits verstehen