API Reference

Navigate: Use the sidebar (left) for any endpoint. Quick links on this page:

• Tracking Endpoints — session/start, event, batch, session/end
• Analytics Endpoints — overview, leads, engine, anomalies
• Forms — GET /forms/config
• Lead Capture — /lead.capture, CRM callback, CRM webhook
• Other Endpoints — tracker.js, form.js, pulse.js, health
• Authentication · Rate Limiting · CORS

---

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)
GET	/analytics/engine/submissions-daily	Lead submissions per day (Analytics Engine; optional filters)
GET	/analytics/engine/by-project	Lead submissions by project
GET	/analytics/engine/by-source	Lead submissions by source
GET	/analytics/engine/by-engagement	Lead submissions by engagement label
GET	/analytics/engine/overview	Lead submission totals and averages
GET	/analytics/engine/projects	Distinct projects (filter options)
GET	/analytics/engine/sources	Distinct sources (filter options)
OPTIONS	/analytics/*	CORS preflight (no auth required)

Forms (multi-form / sites)

Method	Path	Description
GET	/forms/config	Form schema by siteKey + formId (domain-validated)
OPTIONS	/forms/config	CORS preflight

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
POST	/lead.capture/make-callback	Callback for Make.com to send execution log URL (and optional status) for "View in Make.com"
POST	/webhooks/crm/lead	Incoming webhook for CRM lead change events
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. Role-based access: admin key (ANALYTICS_API_KEY) has full access; marketing keys (dashboard-generated in Settings → Marketing API keys, or optional ANALYTICS_MARKETING_API_KEY) have restricted pages and optional PII masking. See Marketing access.

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 backed by D1 (atomic increment). Whitelisted IPs (dashboard Whitelisted IPs) skip rate limiting.

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