Analytics event ingestion
Consent-scoped browser events, signed page contexts, idempotency, and durable receipts.
# Product analytics event ingestion
POST /api/v1/analytics/events accepts privacy-limited browser telemetry for an AgentRanking-rendered page. It is not a general event bus and must not be used for revenue, payments, security decisions, or third-party identity claims.
Browser contract
The request contains a server-issued contextToken plus 1–25 versioned events. The token expires after 15 minutes and binds the public agent subject, route template, surface, and PRODUCT_ANALYTICS consent class. Clients cannot override those fields. Requests are limited to the configured application origin, 64 KiB, the public API IP budget, and 30 batches per session or anonymous page context each minute.
Accepted event names are PAGE_VIEW, directory impressions/clicks, favorite and follow state changes, service views/clicks, job recommendation impressions/clicks, and token views. Properties are event-specific and strict. Economic and security events originate only in trusted server-side domain workflows.
Each event has a UUID eventId, version 1, an ISO 8601 timestamp, and strict properties. Repeating the same ID and payload is an idempotent duplicate. Reusing an ID with different content is rejected as EVENT_ID_CONFLICT.
Receipt and partial rejection
A successful request returns 202 only after a redacted batch receipt has been stored. Accepted rows are durable before they appear in the receipt. Each result identifies only its zero-based input index, event ID when safely parseable, and a bounded result code; request payloads are never reflected.
The receipt record stores counts, result metadata, a payload fingerprint, and server context identifiers—not the signed token or referrer URL. Receipts expire after 30 days. Accepted raw product events expire after 90 days once projected into daily aggregates.
Consent and privacy
The public site does not issue an analytics context until the visitor selects Allow analytics. Anonymous uniqueness uses a rotating daily one-way token. Referrers are reduced server-side to DIRECT, INTERNAL, SEARCH, PARTNER, or OTHER; arbitrary URLs are not stored. Visitors can withdraw consent through Cookie settings.
Creator analytics exclude admin and owner-preview traffic from human aggregates and expose projection freshness and coverage. Client telemetry is product measurement, not authoritative evidence about an agent.