Event Collection

The collection endpoint accepts batches of analytics events from client-side JavaScript. It is intentionally public — no authentication is required.

Collect Events

POST /v1/collect/{orgId}

Authentication: None (public endpoint)

Rate Limit: 60 requests/min per IP

Path Parameters

Parameter	Type	Description
orgId	string	Your organization ID (e.g., org_00000a1B2c3D4e5)

Request Body

{
  "events": [
    {
      "type": "page_view",
      "url": "https://mystore.com/products/organic-bananas",
      "title": "Organic Bananas - My Store",
      "referrer": "https://mystore.com/",
      "timestamp": 1711468800000
    },
    {
      "type": "click",
      "url": "https://mystore.com/products/organic-bananas",
      "element": "button",
      "element_id": "add-to-cart",
      "element_text": "Add to Cart"
    }
  ]
}

Event Fields

All events share a common set of fields. Additional fields vary by event type.

Common Fields

Field	Type	Required	Description
type	string	Yes	Event type (see Tracked Event Types)
url	string	Yes	Page URL where the event occurred
timestamp	integer	No	Client-side Unix timestamp in milliseconds. Server time is used if omitted.

Page View Fields

Field	Type	Description
title	string	Page title
referrer	string	Referring URL

Interaction Fields (click, scroll_depth, form_submit)

Field	Type	Description
element	string	HTML element tag name
element_id	string	Element id attribute
element_class	string	Element CSS class(es)
element_text	string	Visible text (truncated to 100 characters)
scroll_percent	integer	Maximum scroll depth percentage (scroll_depth only)
form_action	string	Form action URL (form_submit only)
form_method	string	Form HTTP method (form_submit only)

Ecommerce Fields

Field	Type	Description
product_id	string	Product identifier
product_name	string	Product display name
product_price	number	Product unit price
product_category	string	Product category
quantity	integer	Item quantity
order_total	number	Total order value (purchase events)
items	array	Order line items (purchase events)

Batch Limits

• Minimum: 1 event per request
• Maximum: 50 events per request (events beyond 50 are silently dropped)

Server-Side Enrichment

Each batch is automatically enriched with:

• request_ip — Client IP address (used for GeoIP lookup)
• user_agent — Browser user agent string
• received_at — Server-side timestamp

Response

202 Accepted — Events queued for processing:

{
  "accepted": 3
}

The accepted count reflects the number of events actually queued (capped at 50).

Error Responses

403 Forbidden — Unknown or inactive organization:

{
  "error": "Unknown organization"
}

422 Unprocessable Entity — Empty or missing events array:

{
  "error": "Events array is required"
}

429 Too Many Requests — Rate limit exceeded:

{
  "error": "Too many requests"
}

Domain Validation

Events are only accepted from domains registered in your site configuration. Requests from unregistered domains are rejected.

CORS

The endpoint returns appropriate CORS headers to allow cross-origin requests from registered domains.

Server-Side Event Collection

An authenticated endpoint for sending events from your backend. Use this for server-side ecommerce tracking (purchase confirmations, refunds), data imports, or any scenario where events originate from your server rather than a browser.

POST /v1/events

Authentication: OAuth Bearer

Scope: insightcore:events.write

Rate Limit: 1,000 requests/min

Request Body

{
  "events": [
    {
      "type": "purchase",
      "url": "https://mystore.com/checkout/complete",
      "order_total": 89.97,
      "items": [
        { "product_id": "prd_00000k1L2m3N4o5", "quantity": 3, "price": 29.99 }
      ]
    }
  ],
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}

Request Fields

The events array accepts the same event fields as the public endpoint.

Field	Type	Required	Description
events	array	Yes	Array of event objects (1–500 per request)
ip	string	No	End-user IP address for GeoIP enrichment. Falls back to the caller's IP if omitted.
user_agent	string	No	End-user user agent string. Falls back to the caller's user agent if omitted.

Key Differences from Public Endpoint

	Public (/v1/collect/{orgId})	Authenticated (/v1/events)
Auth	None	OAuth Bearer token
Organization	Path parameter	Derived from JWT
Rate limit	60/min per IP	1,000/min
Batch size	50 events max	500 events max
Domain validation	Yes	No
Use case	Browser JavaScript	Backend services

Response

202 Accepted:

{
  "accepted": 1
}

Error Responses

401 Unauthorized — Missing or invalid token:

{
  "error": "unauthenticated",
  "message": "Valid authentication credentials are required."
}

422 Unprocessable Entity — Validation error (empty events, missing organization context):

{
  "error": "Organization context is required"
}

---

Changelog

Date	Change
2026-03-28	Added authenticated server-side collection endpoint (POST /v1/events).
2026-03-26	Initial publication.