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 <code>flow_ws_</code>. 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 <code>flow_</code>. Copiez les nouveaux jetons immédiatement, car le secret n’est affiché qu’une seule fois.

2. Authentifier vos requetes

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

En-tete d'autorisation
Authorization: Bearer YOUR_API_KEY

3. Commencer a envoyer des requetes

L’URL de base pour tous les endpoints v1 est : <code>https://analytics.flowsery.com/analytics/api/v1/</code>. Avec un jeton workspace, appelez d’abord <code>GET /websites</code>, puis transmettez <code>websiteId</code> ou <code>domain</code> 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 <code>X-Workspace-Id</code>, 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 <code>GET /workspaces</code> pour les lister, puis envoyez l’id voulu dans <code>X-Workspace-Id</code> à 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 <code>403 Forbidden</code> avec le code <code>workspace_access_denied</code>. 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 reponse

Les reponses reussies retournent un statut 200 OK avec un corps structure comme suit :

Reponse reussie
{
  "status": "success",
  "data": { ... }
}

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

Reponse 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 <code>websiteId</code> ni <code>domain</code>. Une clé de site qui appelle <code>GET /workspaces</code> reçoit aussi 400.<br /><strong>401 Unauthorized</strong> -- Le jeton API est manquant, invalide ou révoqué. Le code <code>token_issuer_lost_access</code> 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> -- <code>workspace_access_denied</code> : l'en-tête X-Workspace-Id désigne un workspace que ces identifiants ne peuvent pas atteindre. <code>subscription_required</code> : l'offre n'inclut plus l'accès à l'API. <code>permission_denied</code> : votre rôle dans le workspace n'a pas la permission <code>flowsery.write</code>, 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 <code>Retry-After</code>. Chaque réponse contient <code>RateLimit-Policy</code>, <code>RateLimit-Limit</code>, <code>RateLimit-Remaining</code> et <code>RateLimit-Reset</code>.<br /><strong>500 Internal Server Error</strong> -- Un problème inattendu s'est produit sur le serveur.
Exemple de requete (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"
    }
  ]
}