API Reference

Tracking Endpoints

All tracking endpoints accept POST with Content-Type: application/json. No authentication required. All responses include CORS headers.

Method	Path	Description
POST	/track/session/start	Start a new tracking session
POST	/track/event	Record a single event
POST	/track/events/batch	Record multiple events (max 100)
POST	/track/session/end	End a session and calculate engagement
OPTIONS	/track/*	CORS preflight

Analytics Endpoints

All analytics endpoints require API key authentication and accept GET only. See Analytics API for full details.

Method	Path	Description
GET	/analytics/overview	Summary stats (sessions, events, visitors)
GET	/analytics/sessions/daily	Daily session counts
GET	/analytics/pages/top	Most viewed pages
GET	/analytics/geo	Country-level distribution
GET	/analytics/engagement	Engagement score buckets
GET	/analytics/sources	Traffic referrer ranking
GET	/analytics/realtime	Active sessions and live stats
GET	/analytics/storage	R2 storage stats
GET	/analytics/leads	Paginated lead listing with filters
GET	/analytics/leads/:id	Lead detail with replay-linked activity
GET	/analytics/leads/projects	Distinct project names for filter dropdowns
GET	/analytics/leads/sources	Distinct sources for filter dropdowns
GET	/analytics/anomalies	Anomaly detection (submission drops, traffic spikes, VPN ratio)
OPTIONS	/analytics/*	CORS preflight (no auth required)

Lead Capture

Method	Path	Description
POST	/lead.capture	Primary lead capture endpoint
POST	/lead.capture/crm-callback	Callback for Make.com to send CRM lead ID after CRM create (Phase 8)
POST	/lead	Deprecated — use /lead.capture (sunset 2026-06-01)
POST	/	Deprecated — use /lead.capture (sunset 2026-06-01)
OPTIONS	/lead.capture	CORS preflight

Other Endpoints

Method	Path	Description
GET	/tracker.js	Serves the frontend tracking script
GET	/form.js	Serves the dynamic form builder script
GET	/pulse.js	Combined tracker + form script; PulseGate.init() defaults endpoint to script origin
GET	/health	Health check ({ status: "ok", timestamp })

Authentication

Analytics endpoints require an API key in one of two headers:

Authorization: Bearer <your-api-key>

or

X-API-Key: <your-api-key>

Requests without a valid key receive 401 Unauthorized with a WWW-Authenticate: Bearer header.

Common Response Format

Success (200):

{
  "session_id": "uuid",
  "visitor_id": "sha256-hash",
  "timestamp": 1740000000000
}

Error (400/401/404/405):

{
  "error": "Description of what went wrong"
}

Rate Limiting

Tracking endpoints (/track/*) are rate-limited per IP using a fixed-window strategy:

Route	Limit
/track/session/start	10 requests/min
/track/session/end	10 requests/min
/track/event	120 requests/min
/track/events/batch	30 requests/min

When rate-limited, the response includes:

• 429 Too Many Requests status
• Retry-After header (seconds until reset)
• X-RateLimit-Remaining and X-RateLimit-Reset headers

CORS Headers

All responses include:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Fingerprint-ID, X-Visitor-ID, Authorization, X-API-Key
Content-Type: application/json