api-reference

1. API-Token oder Website-Schlüssel erstellen

Erstellen Sie ein Workspace-API-Token auf der Seite API Tokens, wenn Sie programmatischen Zugriff auf alle Websites im Workspace benötigen, einschließlich MCP- und OpenClaw-Integrationen. Workspace-Tokens verwenden das Präfix flow_ws_. Für Server-zu-Server-Tracking einer einzelnen Website erstellen Sie einen Website-API-Schlüssel unter Einstellungen > API dieser Website; Website-Schlüssel verwenden das Präfix flow_. Kopieren Sie neue Tokens sofort, da das Secret nur einmal angezeigt wird.

2. Anfragen authentifizieren

Jeder API-Aufruf muss den Authorization-Header mit dem Bearer-Schema enthalten. Verwenden Sie ein flow_ws_-Workspace-Token für API-Zugriff über mehrere Websites oder einen flow_-Website-Schlüssel für eine einzelne Website.

Authorization-Header
Authorization: Bearer YOUR_API_KEY

3. Anfragen stellen

Die Basis-URL für alle v1-Endpunkte lautet: https://analytics.flowsery.com/analytics/api/v1/. Rufen Sie mit einem Workspace-Token zuerst GET /websites auf und übergeben Sie danach websiteId oder domain an Endpunktanfragen. Website-Schlüssel sind bereits an eine Website gebunden und benötigen keinen Selector.

Workspace auswählen

Jeder Aufruf läuft in einem Workspace. Ohne den optionalen Header X-Workspace-Id landet er in Ihrem Standard-Workspace. Eine OAuth-Anmeldung, etwa über den Claude- oder ChatGPT-Connector, kann jeden Workspace erreichen, dem das Mitglied angehört, über Organisationen hinweg: Rufen Sie GET /workspaces auf, um sie aufzulisten, und senden Sie die gewünschte id bei jeder Anfrage in X-Workspace-Id. Ein API-Schlüssel gehört zu einem Workspace, senden Sie also seine eigene id oder lassen Sie den Header weg.

Workspace-Header
X-Workspace-Id: cm8ws1a2b3

Ein Workspace, den der Aufrufer nicht erreichen kann, antwortet mit 403 Forbidden und dem Code workspace_access_denied. Ein API-Schlüssel oder Website-Schlüssel, der mit der id eines anderen Workspace gesendet wird, erhält denselben Fehler.

Fehler beim Workspace-Zugriff
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "cm8ws4c5d6",
  "message": "Sie haben keinen Zugriff auf den Workspace cm8ws4c5d6. Rufen Sie GET /workspaces auf, um Ihre verfügbaren Workspaces aufzulisten, und senden Sie eine dieser IDs im Header X-Workspace-Id."
}

Antwortformat

Erfolgreiche Antworten geben den Status 200 OK mit einer wie folgt strukturierten Antwort zurück:

Erfolgreiche Antwort
{
  "status": "success",
  "data": { ... }
}

Fehler verwenden die normale HTTP-Fehlerantwortform von NestJS.

Fehlerantwort
{
  "message": "Unauthorized",
  "statusCode": 401
}

Standard-Fehlercodes

<strong>400 Bad Request</strong> -- Die Eingabe ist ungültig oder erforderliche Parameter fehlen, etwa ein Workspace-Token ohne websiteId oder domain. Ein Website-Schlüssel, der GET /workspaces aufruft, erhält ebenfalls 400.<br /><strong>401 Unauthorized</strong> -- Das API-Token fehlt, ist ungültig oder widerrufen. Der Code token_issuer_lost_access bedeutet, dass das Mitglied, das den Schlüssel erstellt hat, keinen Zugriff mehr auf den Workspace hat; erstellen Sie einen neuen Schlüssel.<br /><strong>403 Forbidden</strong> -- workspace_access_denied: Der Header X-Workspace-Id nennt einen Workspace, den diese Zugangsdaten nicht erreichen. subscription_required: Der Tarif enthält keinen API-Zugriff mehr. permission_denied: Ihrer Rolle im Workspace fehlt die Berechtigung flowsery.write, die Admins und Editors haben. In der Testphase antworten KI-erkannte Probleme nach den ersten 10 mit "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- Die angeforderte Ressource existiert nicht.<br /><strong>429 Too Many Requests</strong> -- Mehr als 600 Anfragen pro Minute für diesen Schlüssel. Warten Sie die Sekunden aus Retry-After ab. Jede Antwort enthält RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.<br /><strong>500 Internal Server Error</strong> -- Auf dem Server ist ein unerwartetes Problem aufgetreten.
Beispielanfrage (curl)
curl --request GET \
  --url https://analytics.flowsery.com/analytics/api/v1/websites \
  --header 'Authorization: Bearer <workspace-api-token>'
200
{
  "status": "success",
  "data": [
    {
      "id": "cm8abc123",
      "domain": "example.com",
      "timezone": "America/New_York",
      "currency": "USD",
      "trackingId": "flid_abc123"
    }
  ]
}