api-reference

1. Créer un jeton API ou une clé de site

Créez un jeton API workspace depuis la page API Tokens lorsque vous avez besoin d’un accès programmatique à tous les sites du workspace, y compris les intégrations MCP et OpenClaw. Les jetons workspace utilisent le préfixe flow_ws_. Pour le tracking serveur à serveur d’un seul site, créez une clé API de site depuis Settings > API de ce site; les clés de site utilisent le préfixe flow_. Copiez les nouveaux jetons immédiatement, car le secret n’est affiché qu’une seule fois.

2. Authentifier vos requêtes

Chaque appel API doit inclure l’en-tête Authorization avec le schéma Bearer. Utilisez un jeton workspace flow_ws_ pour l’accès API multi-site, ou une clé de site flow_ pour un seul site.

En-tête d'autorisation
Authorization: Bearer YOUR_API_KEY

3. Commencer à envoyer des requêtes

L’URL de base pour tous les endpoints v1 est : https://analytics.flowsery.com/analytics/api/v1/. Avec un jeton workspace, appelez d’abord GET /websites, puis transmettez websiteId ou domain aux requêtes. Les clés de site sont déjà limitées à un site et ne nécessitent pas de sélecteur.

Choisir un workspace

Chaque appel s’exécute dans un workspace. Sans l’en-tête facultatif X-Workspace-Id, il aboutit dans votre workspace par défaut. Une connexion OAuth, comme le connecteur Claude ou ChatGPT, peut atteindre chaque workspace dont son membre fait partie, dans toutes ses organisations : appelez GET /workspaces pour les lister, puis envoyez l’id voulu dans X-Workspace-Id à chaque requête. Une clé API appartient à un seul workspace, envoyez donc son propre id ou omettez l’en-tête.

En-tête de workspace
X-Workspace-Id: cm8ws1a2b3

Un workspace que l’appelant ne peut pas atteindre répond 403 Forbidden avec le code workspace_access_denied. Une clé API ou une clé de site envoyée avec l’id d’un autre workspace reçoit la même erreur.

Erreur d’accès au workspace
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "cm8ws4c5d6",
  "message": "Vous n'avez pas accès à l'espace de travail cm8ws4c5d6. Appelez GET /workspaces pour lister les espaces de travail disponibles, puis envoyez l'un de ces identifiants dans l'en-tête X-Workspace-Id."
}

Format de réponse

Les réponses réussies retournent un statut 200 OK avec un corps structuré comme suit :

Réponse réussie
{
  "status": "success",
  "data": { ... }
}

Les erreurs utilisent la forme normale de réponse d'erreur HTTP NestJS.

Réponse d'erreur
{
  "message": "Unauthorized",
  "statusCode": 401
}

Codes d'erreur standards

<strong>400 Bad Request</strong> -- L'entrée est invalide ou des paramètres requis manquent, par exemple un jeton de workspace sans websiteId ni domain. Une clé de site qui appelle GET /workspaces reçoit aussi 400.<br /><strong>401 Unauthorized</strong> -- Le jeton API est manquant, invalide ou révoqué. Le code token_issuer_lost_access signifie que le membre qui a créé la clé a perdu l'accès au workspace ; créez une nouvelle clé.<br /><strong>403 Forbidden</strong> -- workspace_access_denied : l'en-tête X-Workspace-Id désigne un workspace que ces identifiants ne peuvent pas atteindre. subscription_required : l'offre n'inclut plus l'accès à l'API. permission_denied : votre rôle dans le workspace n'a pas la permission flowsery.write, que détiennent les Admins et les Editors. Pendant l'essai gratuit, les problèmes détectés par l'IA au-delà des 10 premiers répondent "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- La ressource demandée n'existe pas.<br /><strong>429 Too Many Requests</strong> -- Plus de 600 requêtes en une minute pour cette clé. Attendez le nombre de secondes indiqué dans Retry-After. Chaque réponse contient RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset.<br /><strong>500 Internal Server Error</strong> -- Un problème inattendu s'est produit sur le serveur.
Exemple de requête (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"
    }
  ]
}