POST /track/session/start

Starts a new tracking session. Returns a session_id immediately while background processing (D1 writes, KV counters, VPN scoring, R2 archival) continues via waitUntil.

All tracking endpoints support CORS: responses include Access-Control-Allow-Origin: * and the server responds to OPTIONS preflight with the appropriate headers so the tracker can be embedded on any origin (e.g. customer sites calling https://pulsegate.pixleo.com/track/session/start).

Request Body

{
  "fingerprint_id": "sha256-hash",
  "page": "https://example.com/home",
  "visitor_id": "optional-existing-visitor-id",
  "referrer": "https://google.com",
  "device_info": {
    "user_agent": "Mozilla/5.0...",
    "language": "en-US",
    "platform": "MacIntel",
    "hardware_concurrency": 8,
    "device_memory": 16
  },
  "screen": {
    "width": 1920,
    "height": 1080,
    "color_depth": 24,
    "pixel_ratio": 2
  }
}

Field	Required	Description
fingerprint_id	Yes	Browser fingerprint hash from the tracker script
page	Yes	Current page URL
visitor_id	No	Existing visitor ID from localStorage; if omitted, derived from fingerprint
referrer	No	HTTP referrer
device_info	No	Browser/device metadata
screen	No	Screen dimensions

Response (200)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "visitor_id": "a1b2c3d4e5f6...",
  "device_id": "f6e5d4c3b2a1...",
  "timestamp": 1740000000000
}

Background Processing

Runs inside ctx.waitUntil() after the response is sent:

1. Create/update fingerprint record in D1
2. Insert session record in D1
3. Store identity network mapping (fingerprint → IP → ASN)
4. Update KV counters (unique IPs, ASNs, session count)
5. Calculate VPN suspicion score
6. Update fingerprint counters in D1
7. Store session metadata in R2

Errors

Status	Condition
400	Invalid JSON body
400	Missing fingerprint_id or page
405	Non-POST method