API publique & clés API
Accès programmatique à votre espace de travail — lecture des projets, sessions, événements personnalisés et segments, et association d’identifiants clients aux sessions — protégé par des clés API limitées à cet espace.
1. Vue d’ensemble
L’API MousePlayer permet d’extraire les données de votre espace de travail vers vos tableaux de bord, votre entrepôt de données ou vos outils internes. À l’exception de l’association d’identifiants clients aux sessions (identify, clé avec droit d’écriture requise, voir les portées des clés), elle est en lecture seule : aucune donnée ne peut être modifiée ni supprimée via l’API.
- URL de base :
https://www.mouseplayer.com/api/v1/ - Toutes les réponses sont au format JSON.
- Chaque requête est authentifiée par une clé API et automatiquement limitée à l’espace de travail auquel elle appartient — une clé d’un espace ne peut jamais voir les données d’un autre, même accidentellement.
- L’enregistrement complet de relecture de session (mouvements de souris, captures du DOM) n’est pas exposé par l’API. Vous obtenez les métadonnées de session, les pages vues, les événements personnalisés et les segments — suffisamment pour créer des rapports et tableaux de bord sans transférer les données brutes de relecture.
2. Authentification
Créez et gérez vos clés API sous Clés API dans le menu de votre compte (/api-keys). Seuls les propriétaires et administrateurs d’espace de travail peuvent créer ou révoquer des clés.
Gardez votre clé secrète. Elle donne accès en lecture à tout votre espace de travail. La clé complète n’est affichée qu’une seule fois, juste après sa création — conservez-la dans un gestionnaire de mots de passe ou un coffre de secrets. Si vous la perdez, révoquez-la et créez-en une autre.
Envoyez la clé comme jeton Bearer dans l’en-tête Authorization de chaque requête :
Une clé absente, mal formée ou révoquée reçoit une réponse 401 :
Forfait requis
L’API REST fait partie des forfaits Business et Enterprise . Le forfait est celui du propriétaire de l’espace de travail ; les membres invités en bénéficient donc aussi. La vérification a lieu à chaque requête, pas seulement lors de la création d’une clé — si le forfait de l’espace est rétrogradé, les clés existantes cessent de fonctionner et renvoient 403.
Portées des clés
Chaque clé indique sa portée dans son préfixe, pour reconnaître ses droits d’un coup d’œil — dans un fichier .env, un ticket ou un terminal.
| Préfixe | Signification |
|---|---|
mp_ro_ | Lecture seule. Lit les projets, sessions, événements et segments. Ne peut rien modifier. |
mp_rw_ | Lecture et écriture. Les mêmes accès, plus l’association d’identifiants client via le point de terminaison d’identification. |
403 avec un message indiquant la portée de la clé et celle requise par le point de terminaison. La portée ne peut pas être modifiée ensuite — créez une nouvelle clé et révoquez l’ancienne.3. Limites de requêtes
Chaque clé API est limitée à 60 requêtes par minute, sur une fenêtre glissante. Au-delà, les requêtes reçoivent une réponse 429 jusqu’à ce que la fenêtre le permette :
Votre projet nécessite une limite plus élevée ? Contactez l’assistance et présentez-nous votre cas d’usage.
4. Points de terminaison
GET/api/v1/projects
Liste tous les projets (propriétés suivies) de votre espace de travail.
GET/api/v1/projects/{channelid}/sessions
Liste les sessions de visiteurs enregistrées pour un projet, de la plus récente à la plus ancienne. Résultats paginés.
| Paramètre de requête | Description |
|---|---|
page | Numéro de page, par défaut 1. |
per_page | Résultats par page, par défaut 25, maximum 100. |
since | Uniquement les sessions commençant à cette date ou après (YYYY-MM-DD). |
until | Uniquement les sessions commençant à cette date ou avant. |
GET/api/v1/sessions/{session_id}
Métadonnées d’une session et ses pages vues. Les données complètes de relecture sont volontairement exclues — utilisez le lecteur du tableau de bord pour les consulter.
GET/api/v1/sessions/{session_id}/events
Événements personnalisés déclenchés durant une session (ceux que vous envoyez avec mp('event', ...)), avec leurs paramètres.
GET/api/v1/projects/{channelid}/segments
Liste les segments de visiteurs définis pour un projet, qu’ils soient propres au projet ou communs à l’espace de travail.
5. Associer un identifiant client depuis votre serveur
Le navigateur ignore souvent qui se trouve devant l’écran. Dans un produit B2B, l’identité est établie après connexion — sur votre serveur. Dans une boutique, elle l’est à la confirmation de commande. Ce point de terminaison est conçu pour ce moment précis.
POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json
{"user_id": "customer-4711"}
// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
"changed": true, "previous": null, "webhook_queued": true}}L’identifiant apparaît alors dans la liste des sessions, où vous pouvez le rechercher, et le webhook session_identified se déclenche — c’est ainsi qu’il atteint votre CRM.
"changed": false et aucun webhook n’est envoyé. Une commande répétée ne crée pas un second prospect.| Statut | Quand |
|---|---|
400 | Champ manquant, user_id de plus de 128 caractères ou contenant des caractères de contrôle. Nous refusons plutôt que de tronquer — un identifiant raccourci sans avertissement ne correspond à rien dans votre CRM, tout en donnant l’impression d’une réussite. |
404 | La session n’existe pas ou n’appartient pas à votre espace de travail. La réponse est volontairement identique dans les deux cas. |
403 | Le forfait de l’espace de travail n’inclut pas l’API. |
6. Webhooks : vérifier la signature
Les webhooks se configurent par projet sous Intégrations, où se trouve aussi le secret de signature. Chaque livraison contient les en-têtes suivants :
| En-tête | Signification |
|---|---|
X-MousePlayer-Event | Nom de l’événement, par ex. session_identified |
X-MousePlayer-Timestamp | Secondes Unix — incluses dans le texte signé |
X-MousePlayer-Attempt | 1 à la première tentative, davantage lors des suivantes |
X-MousePlayer-Signature | sha256=<hex> |
La signature est un HMAC-SHA256 calculé sur timestamp + "." + raw body, à l'aide du secret de signature de votre projet.
// PHP $erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; } // Node const expected = 'sha256=' + crypto.createHmac('sha256', secret) .update(timestamp + '.' + rawBody).digest('hex');
Livraison et nouvelles tentatives
Une livraison échouée est réessayée après 1 min, 5 min, 15 min, 1 h et 6 h, puis abandonnée. Les réponses 4xx autres que 408 et 429 ne sont pas réessayées — elles signifient "pas de cette façon", et non "pas maintenant". Répondez 2xx rapidement et effectuez le traitement ensuite ; la livraison expire au bout de 10 secondes.
Événements disponibles
| Événement | Déclenchement |
|---|---|
session_identified | Lorsqu’une session reçoit pour la première fois un identifiant client — depuis le navigateur ou l’API |
session_ended | Une fois, à la clôture de la session |
goal_reached | Une fois par session, lorsqu’un événement personnalisé remplit l’un de vos objectifs. Uniquement les objectifs de type « event » — les objectifs d’URL, de durée, de pages vues et d’entonnoir ne sont pas évalués. Contient goal_id, goal_name, goal_value et currency. |
high_value_session | Lorsqu’un visiteur franchit pour la première fois dans la journée le seuil de valeur de ce projet. Le seuil est calculé à partir de votre propre distribution des scores (90e percentile des 90 derniers jours), pas un nombre fixe, et n’existe qu’à partir de 20 visiteurs évalués. Contient visitor_id, value_score, threshold et la session de cette journée qui se prête le mieux à la relecture. |
funnel_dropoff | À la fin d’une session ayant commencé l’un de vos entonnoirs sans le terminer. Indique l’étape où elle s’est arrêtée (dropped_at). Un abandon est une absence d’événement ; il ne peut donc être constaté qu’une fois la session terminée. Les sessions qui n’ont jamais commencé l’entonnoir ne sont pas des abandons et ne déclenchent rien. |
high_friction_session | Une fois par session, lorsque son score de friction atteint le seuil pour la première fois (60 sur 100 par défaut). Contient friction_score, les signaux qui le composent (reasons) et le signal qui a fait franchir le seuil (trigger). |
element_broken | Une fois, lorsqu’un élément suivi ne trouve rien dans aucune page vue vérifiée pendant plusieurs jours — généralement après une refonte. Un nouvel envoi n’a lieu que si le marquage a retrouvé une correspondance puis a de nouveau cessé de fonctionner. Cet événement n’appartient à aucune session : session_id et session_url valent null, link_url ouvre le marquage à la place, et subject_id désigne le marquage — identique pour chaque version, de sorte qu’un nouveau sélecteur défaillant rejoint l’incident ouvert. Contient rule_id, rule_name, selector, page, checked_page_views, window_days et last_matched. Aucune donnée de visiteur. |
element_recovered | Le retour à la normale de element_broken : dès que le marquage retrouve réellement un élément — un nombre insuffisant de pages vues ne suffit pas. Envoyé uniquement si element_broken a été transmis par webhook, et sans commutateur distinct : l’abonnement à element_broken l’inclut. Même valeur de subject_id, pour que PagerDuty résolve l’incident et qu’Opsgenie ferme l’alerte. Contient matched_page_views et checked_page_views en plus. |
anomaly_detected | Une fois par jour, lorsque la veille diffère nettement des 28 jours précédents : beaucoup moins ou plus de sessions, baisse du taux d’atteinte des objectifs, davantage de sessions avec friction ou erreurs JS. Le même indicateur dans le même sens ne produit plus de signalement pendant une semaine (réglable). Cet événement n’appartient à aucune session : session_id et session_url valent null, link_url ouvre la vue d’ensemble du projet, et subject_id désigne l’indicateur, le sens et le jour. Contient metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score ainsi qu’un champ lisible summary et hint. Aucune donnée de visiteur. Pour les Web Vitals, measurements remplace sessions, et page (vide pour l’ensemble du site) ainsi que device (desktop ou mobil) indiquent où cela s’est produit ; link_url ouvre alors l’onglet Web Vitals. |
rage_click | Lorsqu’un clic de rage est détecté |
error_detected | Lors d’une exception côté navigateur |
ce | Abonnement groupé à vos propres événements personnalisés. Il n’inclut pas les événements ci-dessus — ils ont leurs propres commutateurs. |
7. Erreurs & codes de statut
| Statut | Signification |
|---|---|
200 | Réussite. |
401 | Clé API absente, mal formée ou révoquée. |
404 | Le projet ou la session demandé n’existe pas ou n’appartient pas à votre espace de travail. |
429 | Limite de requêtes dépassée — vous envoyez plus de 60 requêtes par minute avec cette clé. |
403 | Le forfait de l’espace de travail n’inclut pas l’API REST. Le message précise le forfait requis et le forfait actuel. |
8. Remarques de sécurité
- Les clés en lecture seule (mp_ro_) ne peuvent rien modifier. Les clés en écriture (mp_rw_) peuvent uniquement associer des identifiants clients ; aucune clé ne peut supprimer de données ni exporter les données brutes de relecture.
- Chaque requête est automatiquement limitée à l’espace de travail de la clé — il est impossible de fournir un autre identifiant d’espace pour voir les données d’autrui.
- Révoquez une clé à tout moment depuis /api-keys ; la révocation est immédiate.
- Traitez votre clé API comme un mot de passe. Si vous la publiez accidentellement dans un dépôt public, révoquez-la immédiatement et créez-en une autre.
Pages d’événements limitées (API v1, 14/10/2026)
GET /api/v1/sessions/{session_id}/events renvoie jusqu’à 100 événements par défaut. Définissez per_page sur un entier de 1 à 100. Suivez pagination.next_cursor en transmettant cursor sans modification à la requête suivante ; conservez la même session et le même espace de travail. Les événements sont triés par created_at et event_id. Les curseurs sont signés et liés à cette session et à cet espace. Aucun total ni numéro de page n’est renvoyé.
Le tableau data et la table params existants restent disponibles. pagination.returned est le nombre réellement renvoyé ; pagination.has_more indique la présence d’une autre page. next_cursor vaut null une fois la lecture terminée. Une réponse est limitée à 524288 octets ; une page peut donc contenir moins d’événements que per_page. Chaque événement renvoie au plus 128 lignes de paramètres ; params_truncated vaut true s’il en existe davantage. Chaque paramètre textuel conserve la limite de 255 caractères de la base. Les paramètres tronqués ne sont pas accessibles par ce point de terminaison. Réduire per_page n’augmente pas la limite de paramètres.
Une taille de page non valide, un curseur modifié ou un curseur destiné à une autre session ou un autre espace renvoie 400. Les données trop volumineuses d’un événement individuel renvoient 413. Les contrôles d’accès existants continuent de renvoyer 401, 403, 404 ou 409 selon le cas.
La limite reste de 60 requêtes authentifiées par clé API et par minute. Son dépassement renvoie 429 avec Retry-After: 60. Si Redis ou le limiteur est indisponible, les requêtes renvoient 503 avec Retry-After: 5 ; elles ne sont jamais acceptées sans limite. Respectez Retry-After et ajoutez un délai aléatoire entre les nouvelles tentatives ; ne réessayez pas en boucle serrée. Les défaillances de la base d’événements renvoient aussi 503. Les curseurs ne figent pas un instantané : des insertions simultanées avec des horodatages antérieurs peuvent nécessiter un nouveau parcours.
GET /api/v1/sessions/s_example/events?per_page=25 GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR
/api/v1/native est une route de contrôle côté serveur réservée à Dev pour l’aperçu du SDK natif. Elle reste désactivée en production. Les clés Bearer côté serveur exigent la portée de lecture pour list/replay et la portée d’écriture pour register/grant/delete/disable. Des contrôles supplémentaires de disponibilité de l’aperçu natif s’appliquent. N’intégrez jamais de clés API permanentes d’espace de travail dans une application mobile.