Stats Endpoint

The stats endpoint receives batched analytics events from the widget, powering the engagement dashboard and analytics reports.

POST /stats

Accepts a batch of analytics events and processes them asynchronously. Events are validated, enriched with server-side dimensions (IP, country, device type), and stored for aggregation.

Request

curl -X POST https://faqsir.com/api/stats \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [
      {
        "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "occurred_at": "2025-03-15T14:30:00.000Z",
        "page_url": "https://example.com/article/my-article",
        "event_category": "faq",
        "event_action": "open",
        "event_label": "revenue-growth",
        "anon_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
        "meta": {
          "source_id": "abc123",
          "faq_key": "revenue-growth"
        }
      }
    ]
  }'

Request Body

{
  "events": [
    {
      "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "occurred_at": "2025-03-15T14:30:00.000Z",
      "page_url": "https://example.com/article/my-article",
      "event_category": "faq",
      "event_action": "open",
      "event_label": "revenue-growth",
      "anon_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
      "meta": {
        "source_id": "abc123",
        "faq_key": "revenue-growth"
      }
    }
  ]
}

Field	Type	Required	Description
events	array	Yes	Array of event objects. Minimum 1, maximum 100 events per request.

Event Object Fields

Field	Type	Required	Description
event_id	string (UUID)	Yes	Client-generated unique identifier for this event, used for deduplication.
occurred_at	string (ISO 8601)	Yes	Timestamp of when the event occurred. Must be within the last 24 hours and not more than 5 minutes in the future.
page_url	string	Yes	The full URL of the page where the event occurred.
event_category	string	Yes	Category of the event (e.g., faq, summary, chat, video, panel).
event_action	string	Yes	The specific action (e.g., open, close, click, view, send).
event_label	string	No	Optional label providing additional context (e.g., the FAQ key or tab name).
anon_id	string (UUID)	Yes	Anonymous visitor identifier, persisted in the browser's localStorage.
meta	object	No	Optional key-value metadata (e.g., source_id, faq_key).

Success Response

Status: 202 Accepted

{
  "accepted": 5,
  "request_id": "req_abc123"
}

Field	Type	Description
accepted	integer	The number of events accepted for processing.
request_id	string	Unique identifier for this batch request, useful for debugging.

The 202 Accepted status indicates events have been queued for asynchronous processing. They will appear in the engagement dashboard after aggregation.

Error Responses

Status	Description	Widget Behaviour
401	Invalid or missing API token	Batch dropped, events lost
402	Subscription expired	Batch dropped, events lost
403	Forbidden	Batch dropped, warning logged to console
422	Validation error (invalid events)	Batch dropped, warning logged to console
429	Rate limited	Retry with exponential backoff (respects Retry-After header)
503	Service unavailable	Retry with exponential backoff

Event Categories

The widget tracks the following event categories:

Category	Description	Example Actions
panel	Panel modal interactions	open, close
summary	Summary tab interactions	view
faq	FAQ accordion interactions	open, close
chat	Chat feature interactions	send, view
video	Video player interactions	play, view

Rate Limiting

The stats endpoint is rate-limited to 1,200 requests per minute per API token. When exceeded, the API returns a 429 Too Many Requests response with a Retry-After header.

The widget handles rate limiting automatically with exponential backoff — no manual intervention is required. See API Limits for full details.

Server-Side Enrichment

The widget sends only client-side data. The API enriches each event with server-side dimensions before storage:

Dimension	Source	Description
IP address	Request header	Client IP, retained for 30 days per privacy policy
Country	IP geolocation	Derived from IP address
Device type	User-Agent header	Categorised as desktop, mobile, or tablet

Batch Processing

Events are processed asynchronously after acceptance. The processing pipeline:

1. Validation — Each event is validated against the rules above
2. Enrichment — Server-side dimensions (IP, country, device) are added
3. Storage — Events are stored as raw data
4. Aggregation — Hourly and daily rollups are computed for dashboard reporting

Next Steps