API pública & claves API
Acceso programático a su espacio de trabajo — consulte proyectos, sesiones, eventos personalizados y segmentos, y asocie ID de cliente a sesiones — protegido por claves API limitadas al espacio de trabajo.
1. Resumen
La API de MousePlayer permite extraer datos del espacio de trabajo a sus paneles, almacén de datos o herramientas internas. Salvo la asociación de ID de cliente a sesiones (identify, requiere una clave con permiso de escritura; véase Ámbitos de las claves), es de solo lectura: no se pueden modificar ni eliminar datos mediante la API.
- URL base:
https://www.mouseplayer.com/api/v1/ - Todas las respuestas son JSON.
- Cada solicitud se autentica con una clave API y se limita automáticamente al espacio al que pertenece — una clave de un espacio nunca puede ver datos de otro, ni siquiera por accidente.
- La grabación completa de reproducción de sesiones (movimientos del ratón y capturas del DOM) no se expone mediante la API. Obtiene metadatos, vistas de página, eventos personalizados y segmentos — suficientes para crear informes y paneles sin transferir los datos brutos de reproducción.
2. Autenticación
Cree y gestione sus claves API en Claves API en el menú de su cuenta (/api-keys). Solo los propietarios y administradores del espacio pueden crear o revocar claves.
Mantenga su clave en secreto. Da acceso de lectura a todo su espacio de trabajo. La clave completa se muestra una sola vez, justo después de crearla — guárdela en un gestor de contraseñas o almacén de secretos. Si la pierde, revóquela y cree otra.
Envíe la clave como token Bearer en la cabecera Authorization de cada solicitud:
Las claves ausentes, mal formadas o revocadas reciben una respuesta 401 :
Plan necesario
La API REST forma parte de los planes Business y Enterprise . Se aplica el plan del propietario del espacio de trabajo, por lo que los miembros invitados también lo heredan. Se comprueba en cada solicitud, no solo al crear la clave — si el espacio pasa a un plan inferior, las claves existentes dejan de funcionar y devuelven 403.
Ámbitos de las claves
Cada clave incluye el ámbito en su prefijo, para reconocer sus permisos con solo mirarla — en un archivo .env, un ticket o un terminal.
| Prefijo | Significado |
|---|---|
mp_ro_ | Solo lectura. Lee proyectos, sesiones, eventos y segmentos. No puede cambiar nada. |
mp_rw_ | Lectura y escritura. Todo lo anterior, más la asociación de ID de cliente mediante el endpoint de identificación. |
403 con un mensaje que indica el ámbito de la clave y el necesario. No se puede cambiar después — cree una clave nueva y revoque la anterior.3. Límites de solicitudes
Cada clave API está limitada a 60 solicitudes por minuto, en una ventana móvil. Si supera el límite, las solicitudes reciben una respuesta 429 hasta que la ventana lo permita:
¿Necesita un límite mayor? Contacte con soporte y explique su caso de uso.
4. Endpoints
GET/api/v1/projects
Lista todos los proyectos (propiedades seguidas) de su espacio de trabajo.
GET/api/v1/projects/{channelid}/sessions
Lista las sesiones de visitantes grabadas para un proyecto, de más recientes a más antiguas. Con paginación.
| Parámetro de consulta | Descripción |
|---|---|
page | Número de página, por defecto 1. |
per_page | Resultados por página, por defecto 25, máximo 100. |
since | Solo sesiones que comienzan en esta fecha o después (YYYY-MM-DD). |
until | Solo sesiones que comienzan en esta fecha o antes. |
GET/api/v1/sessions/{session_id}
Metadatos de una sesión y sus vistas de página. Excluye deliberadamente los datos completos de reproducción — utilice el reproductor del panel para verlos.
GET/api/v1/sessions/{session_id}/events
Eventos personalizados de una sesión (los mismos que envía con mp('event', ...)), incluidos sus parámetros.
GET/api/v1/projects/{channelid}/segments
Lista los segmentos de visitantes definidos para un proyecto, tanto los propios como los comunes al espacio.
5. Asociar un ID de cliente desde su servidor
El navegador a menudo no sabe quién está delante. En un producto B2B la identidad se establece tras iniciar sesión — en su servidor. En una tienda, al confirmar el pedido. Este endpoint está pensado para ese momento.
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}}El ID aparece en la lista de sesiones, se puede buscar allí y se activa el webhook session_identified — así llega a su CRM.
"changed": false y no se envía ningún webhook. Repetir un pedido no crea otro posible cliente.| Estado | Cuándo |
|---|---|
400 | Campo ausente, user_id de más de 128 caracteres o con caracteres de control. Rechazamos en lugar de truncar — un ID acortado sin aviso no coincide con nada en el CRM y aun así parece un éxito. |
404 | La sesión no existe o no pertenece a su espacio. La respuesta es deliberadamente idéntica para ambos casos. |
403 | El plan del espacio no incluye la API. |
6. Webhooks: verificar la firma
Los webhooks se configuran por proyecto en Integraciones, donde también está el secreto de firma. Cada entrega incluye estas cabeceras:
| Cabecera | Significado |
|---|---|
X-MousePlayer-Event | Nombre del evento, p. ej. session_identified |
X-MousePlayer-Timestamp | Segundos Unix — parte del texto firmado |
X-MousePlayer-Attempt | 1 en el primer intento; mayor en los reintentos |
X-MousePlayer-Signature | sha256=<hex> |
La firma es un HMAC-SHA256 sobre timestamp + "." + raw body, con el secreto de firma de su proyecto como clave.
// 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');
Entrega y reintentos
Una entrega fallida se reintenta después de 1 min, 5 min, 15 min, 1 h y 6 h, y luego se abandona. Las respuestas 4xx distintas de 408 y 429 se excluyen de los reintentos — significan "así no", no "ahora no". Responda 2xx rápidamente y procese después; la entrega caduca tras 10 segundos.
Eventos disponibles
| Evento | Se activa |
|---|---|
session_identified | Cuando una sesión recibe por primera vez un ID de cliente — desde el navegador o la API |
session_ended | Una vez, al cerrar la sesión |
goal_reached | Una vez por sesión, cuando un evento personalizado cumple uno de sus objetivos. Solo objetivos de tipo «event» — no se evalúan objetivos de URL, duración, vistas de página ni embudo. Incluye goal_id, goal_name, goal_value y currency. |
high_value_session | Cuando un visitante supera por primera vez en un día el umbral de valor del proyecto. El umbral se calcula a partir de su propia distribución de puntuaciones (percentil 90 de los últimos 90 días), no es un número fijo y no existe hasta evaluar al menos a 20 visitantes. Incluye visitor_id, value_score, threshold y la sesión de ese día más adecuada para reproducir. |
funnel_dropoff | Al terminar una sesión que entró en uno de sus embudos pero no lo completó. Indica el paso donde se detuvo (dropped_at). Un abandono es la ausencia de un evento y solo se conoce al terminar la sesión. Las sesiones que nunca entraron en el embudo no son abandonos ni activan el evento. |
high_friction_session | Una vez por sesión, cuando su puntuación de fricción alcanza el umbral por primera vez (60 de 100 por defecto). Incluye friction_score, las señales que la componen (reasons) y la señal que hizo superar el umbral (trigger). |
element_broken | Una vez, cuando un elemento seguido no encuentra nada en ninguna vista de página comprobada durante varios días — normalmente tras una renovación del sitio. Solo vuelve a activarse después de que la selección encuentre coincidencias y falle de nuevo. Este evento no pertenece a ninguna sesión: session_id y session_url son null, link_url abre la selección en su lugar, y subject_id identifica la selección — igual en cada versión, de modo que un nuevo selector que vuelva a fallar se suma a la incidencia abierta. Incluye rule_id, rule_name, selector, page, checked_page_views, window_days y last_matched. Sin datos de visitantes. |
element_recovered | La recuperación de element_broken: cuando la selección vuelve a encontrar realmente un elemento — no basta con tener pocas vistas de página. Solo se envía si element_broken se envió por webhook, y no tiene interruptor propio: suscribirse a element_broken lo incluye. El mismo subject_id, para que PagerDuty resuelva la incidencia y Opsgenie cierre la alerta. Incluye también matched_page_views y checked_page_views como datos adicionales. |
anomaly_detected | Una vez al día, cuando ayer difirió claramente de los 28 días anteriores: muchas menos o más sesiones, menor tasa de objetivos, más sesiones con fricción o errores JS. La misma métrica y dirección no vuelven a notificarse durante una semana (ajustable). Este evento no pertenece a ninguna sesión: session_id y session_url son null, link_url abre el resumen del proyecto, y subject_id identifica métrica, dirección y día. Incluye metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score y los campos legibles summary y hint. Sin datos de visitantes. Para Web Vitals, measurements sustituye a sessions, y page (vacío para todo el sitio) y device (desktop o mobil) indican dónde ocurrió; link_url abre entonces la pestaña Web Vitals. |
rage_click | Al detectar un clic de rabia |
error_detected | Al producirse una excepción del navegador |
ce | Suscripción conjunta a sus eventos personalizados. Esto no incluye los eventos anteriores — tienen sus propios interruptores. |
7. Errores & códigos de estado
| Estado | Significado |
|---|---|
200 | Éxito. |
401 | Clave API ausente, mal formada o revocada. |
404 | El proyecto o la sesión no existe o no pertenece a su espacio de trabajo. |
429 | Límite de solicitudes superado — envía más de 60 solicitudes por minuto con esta clave. |
403 | El plan del espacio no incluye la API REST. El mensaje indica el plan necesario y el actual. |
8. Notas de seguridad
- Las claves de solo lectura (mp_ro_) no pueden cambiar nada. Las claves de escritura (mp_rw_) solo pueden asociar ID de cliente; ninguna clave permite eliminar datos o exportar datos brutos de reproducción.
- Cada solicitud se limita automáticamente al espacio de la clave — no se puede pasar el ID de otro espacio para ver datos ajenos.
- Revoque una clave en cualquier momento desde /api-keys; la revocación es inmediata.
- Trate la clave API como una contraseña. Si la incluye accidentalmente en un repositorio público, revóquela de inmediato y cree otra.
Páginas de eventos limitadas (API v1, 14/10/2026)
GET /api/v1/sessions/{session_id}/events devuelve hasta 100 eventos por defecto. Defina per_page como un entero de 1 a 100. Siga pagination.next_cursor enviando cursor sin cambios en la siguiente solicitud; mantenga la misma sesión y espacio. Los eventos se ordenan por created_at y event_id. Los cursores están firmados y vinculados a esa sesión y espacio. No se devuelve recuento total ni número de página.
El array data y el mapa params existentes siguen disponibles. pagination.returned es el número realmente devuelto; pagination.has_more indica otra página. next_cursor es null al terminar. Cada respuesta se limita a 524288 bytes, así que una página puede contener menos eventos que per_page. Por evento se devuelven como máximo 128 filas de parámetros; params_truncated es true si hay más. Cada parámetro de texto conserva el límite de 255 caracteres de la base de datos. Los parámetros truncados no están disponibles por este endpoint. Reducir per_page no aumenta el límite de parámetros.
Los tamaños de página inválidos, los cursores alterados o de otra sesión o espacio devuelven 400. Los datos demasiado grandes de un evento individual devuelven 413. Los controles de acceso existentes siguen devolviendo 401, 403, 404 o 409 según corresponda.
El límite sigue siendo 60 solicitudes autenticadas por clave API y minuto. Al agotarse, devuelve 429 con Retry-After: 60. Si Redis o el limitador no están disponibles, las solicitudes devuelven 503 con Retry-After: 5; nunca se admiten sin límite. Respete Retry-After y añada una espera aleatoria entre reintentos; no reintente en un bucle continuo. Los fallos de la base de eventos también devuelven 503. Los cursores no congelan una instantánea: inserciones simultáneas con marcas de tiempo anteriores pueden exigir un nuevo recorrido.
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 es una ruta de control del servidor exclusiva de Dev para la vista previa del SDK nativo. Permanece desactivada en producción. Las claves Bearer del servidor necesitan ámbito de lectura para list/replay y de escritura para register/grant/delete/disable. Se aplican controles adicionales de disponibilidad de la vista previa nativa. Nunca integre claves API permanentes del espacio de trabajo en una aplicación móvil.