Référence de l’API

URL de base : https://api.analytics.house (ou votre propre Worker si vous auto-hébergez). Les réponses sont au format JSON. Les points de terminaison authentifiés nécessitent Authorization: Bearer <token>, obtenu via /auth/login.

Envoyer des événements : POST /collect

Public (sans jeton). Renvoie immédiatement 202 ; les événements sont écrits en arrière-plan.

curl -X POST https://api.analytics.house/collect \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_PROJECT_KEY",
    "events": [
      { "event_name": "pageview", "event_type": "pageview", "path": "/pricing", "session_id": "s1" },
      { "event_name": "signup", "event_type": "custom", "properties": { "plan": "pro" } }
    ]
  }'

Champs d’un événement : event_name (obligatoire), event_type, path, referrer, session_id, user_id, timestamp (ISO 8601), utm_source, utm_medium, utm_campaign, properties (objet). Les robots sont ignorés. Au-delà de la limite de débit, vous recevez 429 avec Retry-After. Si le projet définit une liste de sites autorisés, les requêtes de navigateur provenant de tout autre site reçoivent 403. Les événements d’un même visiteur espacés de 30 minutes au maximum forment une visite, et les balises UTM de la page d’arrivée sont appliquées au reste de la visite. session_id est ignoré sauf si le projet désactive le mode strict, et user_id est toujours stocké sous forme de hachage quotidien.

Compte

• POST /auth/register: { "email", "password" }
• POST /auth/login: renvoie { "token", "user", "expires_at" }
• GET /auth/me: renvoie le profil du compte actuel
• PUT /auth/me: { "email", "current_password" } met à jour l’adresse e-mail du compte et renvoie un jeton actualisé
• POST /auth/change-password: { "current_password", "new_password" }
• DELETE /auth/me: { "password", "code" } supprime définitivement le compte et tous les projets dont il est propriétaire (code uniquement si la 2FA est activée)
• POST /auth/forgot-password: { "email" } envoie par e-mail un lien de réinitialisation à usage unique. La réponse est identique, que le compte existe ou non.
• POST /auth/reset-password: { "token", "password" }
• POST /auth/logout: les sessions reposent sur des jetons sans état : le client se contente donc de supprimer son jeton.
• POST /auth/verify-email: { "token" } issu du lien de l’e-mail de vérification (aucune session requise). POST /auth/verify-email/resend envoie un nouveau lien. Les nouveaux comptes et les adresses modifiées sont d’abord non vérifiés ; les invitations, les rapports et les e-mails d’alerte ne sont envoyés qu’aux adresses vérifiées.

Authentification à deux facteurs (TOTP)

• POST /auth/2fa/setup: { "password" } renvoie un secret et une URI otpauth:// pour votre application d’authentification.
• POST /auth/2fa/enable: { "code" } confirme le premier code et renvoie des codes de récupération à usage unique (affichés une seule fois).
• POST /auth/2fa/disable: { "password", "code" }
• Lorsque la 2FA est activée, POST /auth/login renvoie { "two_factor_required": true, "challenge_token" }. Terminez avec POST /auth/2fa/verify et { "challenge_token", "code" } (un code à 6 chiffres ou un code de récupération) dans les 5 minutes.

Projets

• GET /projects, POST /projects ({ "name" })
• GET | PUT | DELETE /projects/:id. Clés de settings : strict_privacy, geo_detail, ephemeral_raw, ai_assistant, respect_dnt (true/false), k_anonymity (de 0 à 100), allowed_hostnames (liste ; *.example.com couvre les sous-domaines). Les nouveaux projets démarrent avec strict_privacy: true, geo_detail: false, k_anonymity: 5.

Lire les données

• GET /projects/:id/stats?start=ISO&end=ISO: totaux, séries temporelles et répartitions (par défaut les 7 derniers jours, 366 au maximum), y compris les sources (les pages vues sans site référent sont (direct)), la source, le support et la campagne UTM, ainsi que les pages d’entrée et de sortie. Ajoutez compare=1 pour obtenir aussi, sous previous, la période précédente de même durée. Chaque événement personnalisé inclut un conversion_rate (pourcentage de visiteurs qui l’ont déclenché).
• Filtres : ajoutez un ou plusieurs paramètres f=dimension:value, par exemple f=country:DE&f=path:/pricing. Dimensions : path, referrer (utilisez (direct) en l’absence de site référent), country, region, city, browser, device, os, utm_source, utm_medium, utm_campaign, event. Jusqu’à 5 filtres ; les requêtes filtrées lisent les événements bruts, la période est donc limitée à 92 jours.
• GET /projects/:id/props?event=Outbound%20Link&key=url: valeurs les plus fréquentes d’une propriété d’événement (20 au maximum, limite de 92 jours).
• GET /projects/:id/events?limit=100&offset=0: événements individuels, du plus récent au plus ancien (limite de 500 au maximum). Réservé au propriétaire et aux administrateurs ; les lecteurs et les clés de statistiques n’obtiennent que des agrégats.
• GET /projects/:id/realtime: visiteurs des 5 dernières minutes et pages des 30 dernières.

Les statistiques sont mises en cache pendant environ 30 secondes. Consultez Confidentialité et données pour savoir comment les visiteurs sont comptés.

Entonnoirs

Un entonnoir comprend de 2 à 6 étapes ordonnées. Chaque étape est { "type": "page", "value": "/pricing" } (terminez la valeur par * pour une correspondance de préfixe) ou { "type": "event", "value": "signup" }. Les étapes sont comptées par session (un onglet de navigateur), dans l’ordre.

• GET /projects/:id/funnels, POST /projects/:id/funnels ({ "name", "steps" })
• GET /projects/:id/funnels/:funnelId?start=ISO&end=ISO: nombre par étape, conversion depuis l’étape précédente, conversion globale, abandons.
• DELETE /projects/:id/funnels/:funnelId

Liens de partage publics

• POST /projects/:id/share crée (ou renvoie) un jeton de lien en lecture seule ; DELETE /projects/:id/share le révoque.
• GET /public/:token, /public/:token/stats, /public/:token/props: mêmes paramètres que ci-dessus, sans authentification. N’inclut jamais votre clé d’API ni les événements bruts.

Export CSV

• GET /projects/:id/export?start=ISO&end=ISO: les chiffres derrière le tableau de bord (synthèse, séries temporelles, répartitions).
• GET /projects/:id/export?what=events&start=ISO&end=ISO: événements bruts, jusqu’à 20 000 lignes, limite de 92 jours.

Revenus et profondeur de défilement

• Envoyez les revenus dans properties.revenue (nombre) et, en option, properties.currency (ISO 4217, USD par défaut) sur un événement personnalisé.
• GET /projects/:id/revenue: totaux, nombre de commandes, panier moyen et revenu par visiteur, regroupés par devise (jamais additionnés d’une devise à l’autre).
• GET /projects/:id/scroll: échantillons de profondeur de défilement (le script de suivi doit comporter data-scroll="true"). Ces échantillons ne sont comptés ni comme des événements, ni comme des sessions, ni comme des rebonds.

Équipe, clés d’API de statistiques, rapports, import

• GET/POST /projects/:id/members, DELETE /projects/:id/members/:userId, DELETE /projects/:id/invites?email=. Rôles : lecteur (lecture) et administrateur (gestion). Seul le propriétaire gère l’équipe.
• POST /projects/:id/keys renvoie une seule fois une clé de statistiques en lecture seule (ea_sk_...). Utilisez-la comme Authorization: Bearer sur stats, props, realtime, revenue, scroll et funnels. Les événements bruts et la clé d’ingestion ne sont jamais exposés. Révoquez-la avec DELETE /projects/:id/keys/:id.
• GET/PUT /projects/:id/reports (frequency: off | weekly | monthly). POST /projects/:id/reports/test envoie un aperçu à l’adresse e-mail de votre compte (3 par heure). Les e-mails sont envoyés via Cloudflare Email Service.
• POST /projects/:id/import avec { "csv": "date,visitors,..." } : totaux quotidiens issus de Plausible, de Simple Analytics et d’outils similaires. Les dates qui chevauchent des jours déjà collectés sont refusées. DELETE supprime l’import.

Manifeste de confidentialité et proxy Worker sur votre propre domaine

• GET /projects/:id/privacy: renvoie l’état actuel de la rotation du sel cryptographique, l’empreinte Subresource Integrity (sha384) de /tracker.js, les options de confidentialité actives (strict_privacy, ephemeral_raw, k_anonymity) et un script de proxy Cloudflare Worker prêt à déployer sur votre propre domaine.
• GET /public/:token/privacy: manifeste public de vérification de la confidentialité, en lecture seule, pour les tableaux de bord partagés.

Attribution aux recherches IA, Core Web Vitals, bouclier anti-robots, annotations et webhooks

• GET /projects/:id/stats inclut ai_sources (ChatGPT, Perplexity, Claude, Gemini, Copilot, DeepSeek, etc.), channels (7 canaux d’acquisition automatiques) et anomalies (détection des pics et des chutes de trafic par z-score).
• GET /projects/:id/vitals?start=ISO&end=ISO: renvoie score (score d’expérience réelle de 0 à 100), metrics (p50/p75/p95 et pourcentages Bon/Médiocre pour LCP, INP, CLS, TTFB, FCP) et le détail de la latence par route.
• GET /projects/:id/bots?start=ISO&end=ISO: renvoie des comptages quotidiens, respectueux de la vie privée, des robots d’entraînement IA (GPTBot, ClaudeBot, Google-Extended), des assistants de recherche IA (PerplexityBot, OAI-SearchBot) et des robots de moteurs de recherche (Googlebot).
• GET | POST /projects/:id/annotations et DELETE /projects/:id/annotations/:annId : épinglez des lancements de produits et des temps forts marketing à des dates UTC sur la chronologie.
• GET | POST /projects/:id/alerts, DELETE /projects/:id/alerts/:webhookId et POST /projects/:id/alerts/:webhookId/test : configurez des alertes Slack, Discord, HTTPS (protégées contre les attaques SSRF) et par e-mail pour les pics de trafic, les chutes de trafic et les variations d’objectifs. GET /projects/:id/alerts/log liste les alertes envoyées.
• GET /public/:token/badge.svg?metric=visitors|pageviews&period=24h|7d|30d&style=emerald|blue|slate: badge SVG de trafic en direct, à intégrer dans les README GitHub et les pieds de page.

Questions sur vos statistiques et erreurs JavaScript

• POST /projects/:id/ask avec { "question": "Which pages grew this month?" } : répond en langage courant à partir des seuls chiffres agrégés (les événements bruts et les identifiants de visiteurs ne sont jamais transmis à l’IA). Jusqu’à 10 questions par minute et par utilisateur.
• GET /projects/:id/errors?start=ISO&end=ISO: erreurs JavaScript regroupées par message, fichier et ligne. Le script de suivi ne les envoie qu’avec data-errors="true" ; elles ne sont jamais comptées comme du trafic.

Cartes des clics et parcours

• GET /projects/:id/clicks?start=ISO&end=ISO: pages disposant de données de clics. Ajoutez path=/pricing pour obtenir les éléments de cette page (clics, clics de rage et clics morts, part) ; ajoutez selector=... pour obtenir la grille 10 x 10 des points où les clics ont eu lieu. Les éléments ayant reçu moins de clics que le seuil de k-anonymat du projet sont masqués.
• GET /projects/:id/journeys?path=/pricing&start=ISO&end=ISO: pages visitées juste avant et juste après, au sein d’une même visite ; les étapes suivies par moins de visites que le seuil sont regroupées sous « Other ». Lit les événements individuels : la période est donc limitée à 92 jours.
• GET /projects/:id/errors signale par is_new chaque type d’erreur apparu pour la première fois au cours de la période ; des alertes peuvent se déclencher sur new_error.

État du service

GET /public/status est public. Il est surveillé par le service lui-même (une vérification toutes les 15 minutes) et ne constitue pas un SLA.