API pública & chaves de API
Acesso programático ao seu espaço de trabalho — consulte projetos, sessões, eventos personalizados e segmentos e associe IDs de clientes às sessões — protegido por chaves de API limitadas ao espaço de trabalho.
1. Visão geral
A API do MousePlayer permite extrair dados do seu espaço de trabalho para seus próprios painéis, data warehouse ou ferramentas internas. Com exceção da associação de IDs de clientes às sessões (identify, que exige uma chave com escopo de gravação; consulte Escopos das chaves), ela é somente leitura: nenhum dado pode ser alterado ou excluído pela API.
- URL base:
https://www.mouseplayer.com/api/v1/ - Todas as respostas são em JSON.
- Cada solicitação é autenticada com uma chave de API e automaticamente limitada ao espaço de trabalho ao qual a chave pertence — uma chave de um espaço de trabalho nunca pode acessar os dados de outro, nem por acidente.
- A gravação completa da reprodução da sessão (movimentos do mouse, capturas do DOM) não é disponibilizada pela API. Você recebe metadados da sessão, visualizações de página, eventos personalizados e segmentos — o suficiente para criar relatórios e painéis sem transportar os dados brutos da reprodução.
2. Autenticação
Crie e gerencie suas chaves de API em Chaves de API no menu da sua conta (/api-keys). Somente proprietários e administradores do espaço de trabalho podem criar ou revogar chaves.
Mantenha sua chave em segredo. Ela concede acesso de leitura a tudo no seu espaço de trabalho. A chave completa é exibida uma única vez, logo após a criação — armazene-a em um gerenciador de senhas ou cofre de segredos. Se perdê-la, revogue-a e crie outra.
Envie a chave como token Bearer no cabeçalho Authorization de cada solicitação:
Chaves ausentes, malformadas ou revogadas recebem uma resposta 401 :
Requisito de plano
A API REST faz parte dos planos Business e Enterprise . O plano considerado é o do proprietário do espaço de trabalho, e os membros convidados da equipe o herdam. A verificação ocorre em cada solicitação, além do momento de criação da chave — se o espaço de trabalho passar para um plano inferior, as chaves existentes deixam de funcionar e retornam 403.
Escopos das chaves
Cada chave informa seu escopo no próprio prefixo, permitindo reconhecer sua função apenas olhando para ela — em um .env, em um ticket ou em um terminal.
| Prefixo | Significado |
|---|---|
mp_ro_ | Somente leitura. Consulta projetos, sessões, eventos e segmentos. Não pode alterar nada. |
mp_rw_ | Leitura e gravação. Tudo o que está acima, mais a associação de IDs de clientes pelo endpoint identify. |
403 com uma mensagem que informa o escopo da chave e o que o endpoint exige. O escopo não pode ser alterado depois — crie outra chave e revogue a antiga.3. Limites de solicitações
Cada chave de API está limitada a 60 solicitações por minuto, contadas em uma janela móvel. Ao ultrapassar esse limite, as solicitações recebem uma resposta 429 até que a janela permita novas solicitações:
Está criando algo que exige um limite maior? Entre em contato pelo Suporte e conte como pretende usar a API.
4. Endpoints
GET/api/v1/projects
Lista todos os projetos (propriedades monitoradas) do seu espaço de trabalho.
GET/api/v1/projects/{channelid}/sessions
Lista as sessões de visitantes gravadas em um projeto, da mais recente para a mais antiga. Com paginação.
| Parâmetro de consulta | Descrição |
|---|---|
page | Número da página, padrão 1. |
per_page | Resultados por página, padrão 25, máximo 100. |
since | Somente sessões iniciadas nesta data ou depois dela (YYYY-MM-DD). |
until | Somente sessões iniciadas nesta data ou antes dela. |
GET/api/v1/sessions/{session_id}
Metadados de uma única sessão, com suas visualizações de página. Exclui deliberadamente os dados completos da reprodução — para isso, use o player do painel.
GET/api/v1/sessions/{session_id}/events
Eventos personalizados acionados durante uma sessão (os mesmos que você envia com mp('event', ...)), incluindo seus parâmetros.
GET/api/v1/projects/{channelid}/segments
Lista os segmentos de visitantes definidos para um projeto, tanto os específicos do projeto quanto os de todo o espaço de trabalho.
5. Associar um ID de cliente pelo backend
O navegador muitas vezes não sabe quem está usando o site. Em um produto B2B, a identidade é definida após o login — no seu backend. Em uma loja, ela é definida na confirmação do pedido. Este endpoint existe exatamente para esse 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}}O ID passa a aparecer na lista de sessões, onde pode ser pesquisado, e o webhook session_identified é acionado — é assim que a informação chega ao seu CRM.
"changed": false e nenhum webhook é enviado. A repetição de um pedido não cria um segundo lead.| Status | Quando |
|---|---|
400 | Campo ausente, user_id com mais de 128 caracteres ou contendo caracteres de controle. Rejeitamos em vez de truncar — um ID encurtado silenciosamente não corresponde a nada no seu CRM e ainda parece indicar sucesso. |
404 | A sessão não existe ou não pertence ao seu espaço de trabalho. A resposta é deliberadamente igual nos dois casos. |
403 | O plano do espaço de trabalho não inclui a API. |
6. Webhooks: verificar a assinatura
Os webhooks são configurados por projeto em Integrações, onde você também encontra o segredo de assinatura. Cada entrega inclui estes cabeçalhos:
| Cabeçalho | Significado |
|---|---|
X-MousePlayer-Event | Nome do evento, por exemplo, session_identified |
X-MousePlayer-Timestamp | Segundos Unix — parte do texto assinado |
X-MousePlayer-Attempt | 1 na primeira tentativa, maior nas seguintes |
X-MousePlayer-Signature | sha256=<hex> |
A assinatura é um HMAC-SHA256 de timestamp + "." + raw body, calculado com o segredo de assinatura do projeto.
// 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 e novas tentativas
Uma entrega com falha é tentada novamente após 1 min, 5 min, 15 min, 1 h e 6 h, e depois é abandonada. Respostas 4xx diferentes de 408 e 429 , não geram novas tentativas — significam "não desta forma", em vez de "não agora". Responda 2xx rapidamente e processe a tarefa depois; a entrega expira após 10 segundos.
Eventos disponíveis
| Evento | Acionado |
|---|---|
session_identified | Quando uma sessão recebe um ID de cliente pela primeira vez — pelo navegador ou pela API |
session_ended | Uma vez, quando a sessão é encerrada |
goal_reached | Uma vez por sessão, quando um evento personalizado atinge uma das suas metas. Somente metas do tipo “event” — metas de URL, duração, visualização de página e funil não são avaliadas. Inclui goal_id, goal_name, goal_value e currency. |
high_value_session | Quando um visitante ultrapassa pela primeira vez no dia o limite de valor deste projeto. O limite é derivado da sua própria distribuição de pontuações (percentil 90 dos últimos 90 dias), em vez de um número fixo, e só existe depois que pelo menos 20 visitantes recebem uma pontuação. Inclui visitor_id, value_score, threshold e a sessão mais relevante para assistir naquele dia. |
funnel_dropoff | Ao final de uma sessão que entrou em um dos seus funis, mas não o concluiu. Informa a etapa em que parou (dropped_at). Um abandono é a ausência de um evento, então só pode ser identificado depois que a sessão termina. Sessões que nunca entraram no funil não são abandonos e não acionam o evento. |
high_friction_session | Uma vez por sessão, quando a pontuação de atrito atinge o limite pela primeira vez (padrão: 60 de 100). Inclui friction_score, os sinais que contribuíram para ela (reasons) e o sinal que ultrapassou o limite (trigger). |
element_broken | Uma vez, quando um elemento monitorado não é encontrado em nenhuma visualização de página verificada durante vários dias — geralmente após uma reformulação do site. O evento só é acionado novamente depois que a marcação volta a encontrar uma correspondência e deixa de funcionar outra vez. Este evento não pertence a nenhuma sessão: session_id e session_url são null, link_url abre a marcação, e subject_id identifica a marcação — o mesmo valor em todas as versões, para que um novo seletor que deixe de funcionar novamente seja associado ao incidente aberto. Inclui rule_id, rule_name, selector, page, checked_page_views, window_days e last_matched. Sem dados de visitantes. |
element_recovered | A confirmação de normalização de element_broken: quando a marcação realmente volta a encontrar um elemento — um número insuficiente de visualizações de página não basta. Só é enviada se element_broken tiver sido enviado por webhook e não tem um controle próprio: assinar element_broken também inclui este evento. O mesmo subject_id, para que o PagerDuty resolva o incidente e o Opsgenie feche o alerta. Inclui também matched_page_views e checked_page_views . |
anomaly_detected | Uma vez por dia, quando o dia anterior diferiu claramente dos 28 dias precedentes: muito menos ou muito mais sessões, queda na taxa de metas, mais sessões com atrito ou com erros de JS. A mesma métrica na mesma direção não gera novos alertas durante uma semana (ajustável). Este evento não pertence a nenhuma sessão: session_id e session_url são null, link_url abre a visão geral do projeto, e subject_id identifica métrica, direção e dia. Inclui metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score e os textos legíveis summary e hint. Sem dados de visitantes. Para Web Vitals, measurements substitui sessions, e page (vazio para o site inteiro) e device (desktop ou mobil) indicam onde ocorreu; link_url então abre a aba Web Vitals. |
rage_click | Ao detectar um clique de raiva |
error_detected | Ao ocorrer uma exceção no frontend |
ce | Assinatura conjunta dos seus próprios eventos personalizados. Ela não inclui os eventos acima — eles têm controles próprios. |
7. Erros & códigos de status
| Status | Significado |
|---|---|
200 | Sucesso. |
401 | Chave de API ausente, malformada ou revogada. |
404 | O projeto ou a sessão solicitados não existem ou não pertencem ao seu espaço de trabalho. |
429 | Limite de solicitações excedido — você está enviando mais de 60 solicitações por minuto com esta chave. |
403 | O plano do espaço de trabalho não inclui a API REST. A mensagem informa tanto o plano exigido quanto o atual. |
8. Observações de segurança
- Chaves somente leitura (mp_ro_) não podem alterar nada. Chaves de gravação (mp_rw_) só podem associar IDs de clientes; nenhuma chave pode excluir dados nem exportar dados brutos de reprodução.
- Cada solicitação é automaticamente limitada ao espaço de trabalho da própria chave — não é possível informar o ID de outro espaço de trabalho para acessar dados de terceiros.
- Revogue uma chave a qualquer momento em /api-keys; a revogação entra em vigor imediatamente.
- Trate sua chave de API como uma senha. Se você a incluir acidentalmente em um commit de um repositório público, revogue-a imediatamente e crie outra.
Páginas de eventos com limites (API v1, 14 de outubro de 2026)
GET /api/v1/sessions/{session_id}/events retorna até 100 eventos por padrão. Defina per_page como um inteiro de 1 a 100. Siga pagination.next_cursor enviando cursor sem alterações na próxima solicitação; mantenha a mesma sessão e o mesmo espaço de trabalho. Os eventos são ordenados por created_at e event_id. Os cursores são assinados e vinculados à sessão e ao espaço de trabalho. Não são retornados uma contagem total nem um número de página.
O array data e o mapa params existentes continuam disponíveis. pagination.returned é a quantidade efetivamente retornada; pagination.has_more indica que há outra página. next_cursor é null quando a consulta termina. A resposta é limitada a 524288 bytes, então uma página pode conter menos eventos do que per_page. Cada evento retorna no máximo 128 linhas de parâmetros; params_truncated é true se houver mais. Parâmetros de texto individuais mantêm o limite de 255 caracteres do banco de dados. Parâmetros truncados não ficam disponíveis por este endpoint. Reduzir per_page não aumenta o limite de parâmetros.
Tamanhos de página inválidos, cursores alterados e cursores de outra sessão ou espaço de trabalho retornam 400. Dados de um evento individual acima do limite retornam 413. As verificações de acesso existentes continuam retornando 401, 403, 404 ou 409, conforme o caso.
O limite continua sendo de 60 solicitações autenticadas por chave de API por minuto. Ao esgotá-lo, a resposta é 429 com Retry-After: 60. Se o Redis ou o limitador estiver indisponível, as solicitações retornam 503 com Retry-After: 5; elas nunca são aceitas sem limite. Respeite Retry-After e acrescente um tempo de espera aleatório; não repita solicitações em um loop sem pausa. Falhas no banco de dados de eventos também retornam 503. Os cursores não fixam uma captura estática dos dados: inserções simultâneas com carimbos de data e hora mais antigos podem exigir uma nova varredura.
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 é uma rota de controle do backend exclusiva do ambiente Dev para a prévia do SDK nativo. Ela permanece desativada em produção. Chaves Bearer do backend precisam de escopo de leitura para list/replay e de gravação para register/grant/delete/disable. Aplicam-se verificações adicionais de disponibilidade da prévia nativa. Nunca incorpore chaves permanentes de API do espaço de trabalho em um aplicativo móvel.