API Reference

TideMeter exposes a RESTful API for data collection, analytics retrieval, and application management.

Authentication

Most API endpoints require authentication via the payload-token cookie or Bearer token.

# Login
curl -X POST https://your-instance.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'
 
# Response includes a token — use it in subsequent requests
# As a cookie:
#   Cookie: payload-token=<token>
# Or as a Bearer token:
#   Authorization: Bearer <token>

Event Collection

POST /api/collect

Receives page view and custom events from the tracking script. No authentication required. CORS enabled.

Request Body (validated with Zod):

{
  "websiteId": "your-website-id",
  "url": "/blog/hello-world",
  "referrer": "https://google.com",
  "title": "Hello World — My Blog",
  "screen": "1920x1080",
  "language": "en-US",
  "name": "pageview",
  "data": { "key": "value" },
  "userId": "optional-user-id"
}

Response: 202 Accepted — Events are buffered server-side (100 events or 5s flush, max 10K buffer).

Server-side processing:

1. Validates website exists and is active (cached with 5-min TTL)
2. Validates Origin header matches the registered website domain (anti-spam)
3. Parses User-Agent for browser, OS, and device type
4. Filters bots using UA regex patterns
5. Generates visitorId via SHA-256 hash of (websiteId + IP + UA + daily salt)
6. Generates sessionId via SHA-256 hash (30-minute windows)
7. Extracts UTM parameters and referrer data
8. Buffers event for batch database insert

Note: The tracker script’s Origin header is validated against the domain field registered for the website in TideMeter. Requests without an Origin header (e.g. server-side calls) are allowed through.

Statistics Endpoints

All stats endpoints require authentication (via payload-token cookie or Bearer token) and verify the authenticated user owns the requested website. Admins can access all websites.

Endpoints follow the pattern /api/stats/[websiteId]/....

GET /api/stats/[websiteId]/summary

Returns aggregate metrics for a date range.

Query Parameters:

Response:

{
  "visitors": 12847,
  "pageviews": 38291,
  "sessions": 18432,
  "bounceRate": 42.3,
  "avgDuration": 154,
  "viewsPerVisit": 2.08
}

GET /api/stats/[websiteId]/timeseries

Returns time-bucketed analytics data.

Query Parameters:

Response:

{
  "data": [
    {
      "date": "2025-01-01",
      "visitors": 423,
      "pageviews": 891,
      "sessions": 512
    },
    { "date": "2025-01-02", "visitors": 398, "pageviews": 845, "sessions": 478 }
  ],
  "interval": "day"
}

GET /api/stats/[websiteId]/breakdown

Returns metrics broken down by a property.

Query Parameters:

Breakdown properties: url_path, referrer_domain, country, region, city, browser, browser_version, os, os_version, device_type, screen_size, utm_source, utm_medium, utm_campaign, utm_content, utm_term, entry_page, exit_page, hostname, page_title

Response:

{
  "property": "browser",
  "data": [
    { "value": "Chrome", "visitors": 7200, "percentage": 56.1 },
    { "value": "Firefox", "visitors": 2800, "percentage": 21.8 },
    { "value": "Safari", "visitors": 1847, "percentage": 14.4 }
  ],
  "total": 12847
}

GET /api/stats/[websiteId]/active

Returns the number of currently active visitors (last 30 minutes). Cached for 30 seconds.

Response:

{ "active": 42 }

GET /api/stats/[websiteId]/visitors

Returns a paginated list of visitors with search.

Query Parameters:

GET /api/stats/[websiteId]/funnel

Performs funnel conversion analysis based on configured funnel steps.

GET /api/stats/[websiteId]/retention

Returns cohort retention data with configurable granularity (day, week, month).

Health Check

GET /api/health

Returns the health status of the application. No authentication required.

Response:

{
  "status": "ok",
  "timestamp": "2025-04-05T12:00:00.000Z"
}

PayloadCMS REST API

PayloadCMS provides automatic REST endpoints for all collections:

Users

Websites

Teams

Team Members

API Keys

Funnels

For full PayloadCMS REST API documentation, see the PayloadCMS docs .