Referencia de la API

URL base: https://api.analytics.house (o tu propio Worker si alojas el servicio por tu cuenta). Las respuestas son JSON. Los endpoints autenticados necesitan Authorization: Bearer <token> obtenido de /auth/login.

Enviar eventos: POST /collect

Público (sin token). Devuelve 202 de inmediato; los eventos se escriben en segundo plano.

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" } }
    ]
  }'

Campos del evento: event_name (obligatorio), event_type, path, referrer, session_id, user_id, timestamp (ISO 8601), utm_source, utm_medium, utm_campaign, properties (objeto). Los bots se ignoran. Si superas el límite de frecuencia, recibes 429 con Retry-After. Si el proyecto tiene una lista de sitios web permitidos, las solicitudes de navegador desde cualquier otro sitio reciben 403. Los eventos del mismo visitante separados por 30 minutos como máximo forman una visita, y las etiquetas UTM de la página de entrada se trasladan al resto de la visita. session_id se ignora salvo que el proyecto desactive el modo estricto, y user_id siempre se almacena como hash diario.

Cuenta

• POST /auth/register: { "email", "password" }
• POST /auth/login: devuelve { "token", "user", "expires_at" }
• GET /auth/me: devuelve el perfil de la cuenta actual
• PUT /auth/me: { "email", "current_password" } actualiza el correo electrónico de la cuenta y devuelve un token renovado
• POST /auth/change-password: { "current_password", "new_password" }
• DELETE /auth/me: { "password", "code" } elimina de forma permanente la cuenta y todos los proyectos de los que es propietaria (code solo si la verificación en dos pasos está activada)
• POST /auth/forgot-password: { "email" } envía por correo electrónico un enlace de restablecimiento de un solo uso. La respuesta es la misma tanto si la cuenta existe como si no.
• POST /auth/reset-password: { "token", "password" }
• POST /auth/logout: las sesiones son tokens sin estado, así que el cliente simplemente descarta su token.
• POST /auth/verify-email: { "token" } del enlace incluido en el correo de verificación (no requiere sesión). POST /auth/verify-email/resend envía un enlace nuevo. Las cuentas nuevas y las direcciones modificadas empiezan sin verificar; las invitaciones, los informes y los correos de alerta solo llegan a direcciones verificadas.

Verificación en dos pasos (TOTP)

• POST /auth/2fa/setup: { "password" } devuelve un secreto y una URI otpauth:// para tu aplicación de autenticación.
• POST /auth/2fa/enable: { "code" } confirma el primer código y devuelve códigos de recuperación de un solo uso (se muestran una sola vez).
• POST /auth/2fa/disable: { "password", "code" }
• Con la verificación en dos pasos activada, POST /auth/login devuelve { "two_factor_required": true, "challenge_token" }. Complétala con POST /auth/2fa/verify y { "challenge_token", "code" } (un código de 6 dígitos o un código de recuperación) en un plazo de 5 minutos.

Proyectos

• GET /projects, POST /projects ({ "name" })
• GET | PUT | DELETE /projects/:id. Claves de settings: strict_privacy, geo_detail, ephemeral_raw, ai_assistant, respect_dnt (true/false), k_anonymity (de 0 a 100), allowed_hostnames (lista; *.example.com incluye los subdominios). Los proyectos nuevos empiezan con strict_privacy: true, geo_detail: false, k_anonymity: 5.

Consultar datos

• GET /projects/:id/stats?start=ISO&end=ISO: totales, series temporales y desgloses (de forma predeterminada, los últimos 7 días; máximo 366), incluidas las fuentes (las páginas vistas sin sitio de referencia aparecen como (direct)), la fuente, el medio y la campaña UTM, y las páginas de entrada y de salida. Añade compare=1 para obtener también el periodo anterior de la misma duración en previous. Cada evento personalizado incluye un conversion_rate (porcentaje de visitantes que lo activaron).
• Filtros: añade uno o varios parámetros f=dimension:value, por ejemplo f=country:DE&f=path:/pricing. Dimensiones: path, referrer (usa (direct) para indicar que no hay sitio de referencia), country, region, city, browser, device, os, utm_source, utm_medium, utm_campaign, event. Hasta 5 filtros; las consultas filtradas leen los eventos en bruto, por lo que el intervalo está limitado a 92 días.
• GET /projects/:id/props?event=Outbound%20Link&key=url: valores principales de una propiedad de evento (hasta 20; límite de 92 días).
• GET /projects/:id/events?limit=100&offset=0: eventos individuales, del más reciente al más antiguo (límite de hasta 500). Solo para el propietario y los administradores; los lectores y las claves de estadísticas solo obtienen datos agregados.
• GET /projects/:id/realtime: visitantes de los últimos 5 minutos y páginas de los últimos 30.

Las estadísticas se guardan en caché durante unos 30 segundos. Consulta Privacidad y datos para saber cómo se cuentan los visitantes.

Embudos

Un embudo tiene de 2 a 6 pasos ordenados. Cada paso es { "type": "page", "value": "/pricing" } (termina el valor con * para buscar por prefijo) o { "type": "event", "value": "signup" }. Los pasos se cuentan por sesión (una pestaña del navegador) y en orden.

• GET /projects/:id/funnels, POST /projects/:id/funnels ({ "name", "steps" })
• GET /projects/:id/funnels/:funnelId?start=ISO&end=ISO: recuento por paso, conversión desde el paso anterior, conversión total y abandono.
• DELETE /projects/:id/funnels/:funnelId

Enlaces públicos para compartir

• POST /projects/:id/share crea (o devuelve) un token de enlace de solo lectura; DELETE /projects/:id/share lo revoca.
• GET /public/:token, /public/:token/stats, /public/:token/props: los mismos parámetros que arriba, sin autenticación. Nunca incluye tu clave de API ni los eventos en bruto.

Exportación a CSV

• GET /projects/:id/export?start=ISO&end=ISO: las cifras que hay detrás del panel (resumen, series temporales, desgloses).
• GET /projects/:id/export?what=events&start=ISO&end=ISO: eventos en bruto, hasta 20 000 filas, límite de 92 días.

Ingresos y profundidad de desplazamiento

• Envía los ingresos como properties.revenue (número) y, opcionalmente, properties.currency (ISO 4217; USD de forma predeterminada) en un evento personalizado.
• GET /projects/:id/revenue: totales, número de pedidos, valor medio del pedido e ingresos por visitante, agrupados por moneda (nunca se suman entre monedas distintas).
• GET /projects/:id/scroll: muestras de profundidad de desplazamiento (el script de seguimiento debe tener data-scroll="true"). Estas muestras no cuentan como eventos, sesiones ni rebotes.

Equipo, claves de API de estadísticas, informes, importación

• GET/POST /projects/:id/members, DELETE /projects/:id/members/:userId, DELETE /projects/:id/invites?email=. Roles: lector (lectura) y administrador (gestión). Solo el propietario gestiona el equipo.
• POST /projects/:id/keys devuelve una sola vez una clave de estadísticas de solo lectura (ea_sk_...). Úsala como Authorization: Bearer en stats, props, realtime, revenue, scroll y funnels. Los eventos en bruto y la clave de ingesta nunca quedan expuestos. Revócala con DELETE /projects/:id/keys/:id.
• GET/PUT /projects/:id/reports (frequency: off | weekly | monthly). POST /projects/:id/reports/test envía una vista previa al correo electrónico de tu cuenta (3 por hora). Los correos se envían a través de Cloudflare Email Service.
• POST /projects/:id/import con { "csv": "date,visitors,..." }: totales diarios de Plausible, Simple Analytics y servicios similares. Se rechazan las fechas que se solapan con días ya recopilados. DELETE elimina la importación.

Manifiesto de privacidad y proxy de Worker propio

• GET /projects/:id/privacy: devuelve el estado de rotación de la sal criptográfica activa, el hash de Subresource Integrity (sha384) de /tracker.js, los indicadores de la política de privacidad activos (strict_privacy, ephemeral_raw, k_anonymity) y un script de proxy propio de Cloudflare Worker listo para desplegar.
• GET /public/:token/privacy: manifiesto público de verificación de privacidad, de solo lectura, para paneles compartidos.

Atribución de búsquedas con IA, Core Web Vitals, escudo contra bots, anotaciones y webhooks

• GET /projects/:id/stats incluye ai_sources (ChatGPT, Perplexity, Claude, Gemini, Copilot, DeepSeek, etc.), channels (7 canales de adquisición automáticos) y anomalies (detección de picos y caídas de tráfico mediante la puntuación z).
• GET /projects/:id/vitals?start=ISO&end=ISO: devuelve score (puntuación de experiencia real de 0 a 100), metrics (p50/p75/p95 y porcentajes de Bueno/Deficiente para LCP, INP, CLS, TTFB, FCP) y un desglose de la latencia por ruta.
• GET /projects/:id/bots?start=ISO&end=ISO: devuelve recuentos diarios, respetuosos con la privacidad, de rastreadores de entrenamiento de IA (GPTBot, ClaudeBot, Google-Extended), asistentes de búsqueda con IA (PerplexityBot, OAI-SearchBot) y bots de búsqueda (Googlebot).
• GET | POST /projects/:id/annotations y DELETE /projects/:id/annotations/:annId: marca lanzamientos de productos e hitos de marketing en fechas UTC de la cronología.
• GET | POST /projects/:id/alerts, DELETE /projects/:id/alerts/:webhookId y POST /projects/:id/alerts/:webhookId/test: configura alertas por Slack, Discord, HTTPS (con protección contra SSRF) y correo electrónico para picos de tráfico, caídas de tráfico y cambios en los objetivos. GET /projects/:id/alerts/log muestra las alertas enviadas.
• GET /public/:token/badge.svg?metric=visitors|pageviews&period=24h|7d|30d&style=emerald|blue|slate: insignia SVG de tráfico en tiempo real para insertar en los README de GitHub y en pies de página.

Preguntas sobre tus datos y errores de JavaScript

• POST /projects/:id/ask con { "question": "Which pages grew this month?" }: responde en lenguaje sencillo usando solo cifras agregadas (los eventos en bruto y los identificadores de visitante nunca llegan a la IA). Hasta 10 preguntas por minuto y usuario.
• GET /projects/:id/errors?start=ISO&end=ISO: errores de JavaScript agrupados por mensaje, archivo y línea. El script de seguimiento solo los envía con data-errors="true"; nunca cuentan como tráfico.

Mapas de clics y recorridos

• GET /projects/:id/clicks?start=ISO&end=ISO: páginas con datos de clics. Añade path=/pricing para obtener sus elementos (clics, clics de frustración y sin respuesta, porcentaje del total); añade selector=... para obtener la cuadrícula de 10 x 10 con la posición de los clics. Se ocultan los elementos con menos clics que el umbral de k-anonimato del proyecto.
• GET /projects/:id/journeys?path=/pricing&start=ISO&end=ISO: páginas visitadas justo antes y justo después, dentro de una misma visita; los pasos realizados por menos visitas que el umbral se agrupan en "Other". Lee eventos individuales, por lo que el intervalo está limitado a 92 días.
• GET /projects/:id/errors marca con is_new cada tipo de error que apareció por primera vez en el periodo; las alertas pueden activarse con new_error.

Estado

GET /public/status es público. Se supervisa a sí mismo (una comprobación cada 15 minutos) y no constituye un SLA.