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 <code>flow_ws_</code>. 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 <code>flow_</code>. 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 <code>flow_ws_</code>-Workspace-Token für API-Zugriff über mehrere Websites oder einen <code>flow_</code>-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: <code>https://analytics.flowsery.com/analytics/api/v1/</code>. Rufen Sie mit einem Workspace-Token zuerst <code>GET /websites</code> auf und übergeben Sie danach <code>websiteId</code> oder <code>domain</code> 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 <code>X-Workspace-Id</code> 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 <code>GET /workspaces</code> auf, um sie aufzulisten, und senden Sie die gewünschte id bei jeder Anfrage in <code>X-Workspace-Id</code>. 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 <code>403 Forbidden</code> und dem Code <code>workspace_access_denied</code>. 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 zurueck:

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 <code>websiteId</code> oder <code>domain</code>. Ein Website-Schlüssel, der <code>GET /workspaces</code> aufruft, erhält ebenfalls 400.<br /><strong>401 Unauthorized</strong> -- Das API-Token fehlt, ist ungültig oder widerrufen. Der Code <code>token_issuer_lost_access</code> 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> -- <code>workspace_access_denied</code>: Der Header X-Workspace-Id nennt einen Workspace, den diese Zugangsdaten nicht erreichen. <code>subscription_required</code>: Der Tarif enthält keinen API-Zugriff mehr. <code>permission_denied</code>: Ihrer Rolle im Workspace fehlt die Berechtigung <code>flowsery.write</code>, 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 <code>Retry-After</code> ab. Jede Antwort enthält <code>RateLimit-Policy</code>, <code>RateLimit-Limit</code>, <code>RateLimit-Remaining</code> und <code>RateLimit-Reset</code>.<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"
    }
  ]
}