> API Reference

REST API for stats, bot management, campaigns, experiments, and performance metrics.

Authentication

All API endpoints (except /api/health) require one of:

• Bearer token: Authorization: Bearer <ECHELON_SECRET>
• Session cookie: echelon_session from password login

Cookie-authenticated POST/PATCH/DELETE requests require CSRF validation (Origin or Referer header must match the server host).

Public Endpoints

Returns the tracker script with embedded WASM proof-of-work challenge. No auth required.

Pageview beacon. Returns a 1x1 transparent GIF. Query params include path, site ID, session ID, PoW token, screen dimensions, and UTM data. No auth required.

Behavioral events endpoint (via sendBeacon). Accepts JSON with event array, site ID, and PoW token. Returns 204 No Content. Max 16 KB body, max 20 events per request. No auth required.

Health check. No auth required.

{ "status": "ok", "service": "Echelon Analytics" }

Stats

Overview statistics for a site. Visitors, pageviews, top pages, devices, countries, referrers, daily trends. days defaults to 30 (max 730).

Realtime stats: active visitors, pageviews, and active paths from the last 5 minutes.

Summary across all sites.

Live system vitals: in-memory buffer sizes and 24h aggregates.

{
  "buffers": { "views": 42, "events": 17 },
  "last_24h": {
    "total_views": 1234,
    "human_views": 1100,
    "bot_views": 134,
    "unique_visitors": 890
  }
}

Campaign statistics. Optional id param for detailed breakdown by source, medium, content, and term. days defaults to 30 (max 90).

Experiment statistics with variant conversion rates and significance testing.

Campaigns

List all UTM campaigns.

[{
  "id": "spring-2026",
  "name": "Spring Launch",
  "utm_campaign": "spring-2026",
  "site_id": "default",
  "status": "active",
  "created_at": "2026-03-01T00:00:00Z"
}]

Create a campaign. Returns 201.

# Request
{
  "id": "spring-2026",
  "name": "Spring Launch",
  "utm_campaign": "spring-2026",
  "site_id": "default"
}

# Response
{ "created": "spring-2026" }

id must be alphanumeric plus ._- (max 128 chars). site_id defaults to "default".

Update campaign status.

{ "status": "active" | "paused" | "archived" }

Delete a campaign. Returns { "deleted": "campaign-id" }.

Experiments

List all A/B experiments with variants.

Create an experiment. Returns 201.

{
  "experiment_id": "checkout-v2",
  "name": "Checkout Redesign",
  "description": "Test new checkout flow",
  "metric_event_type": "purchase",
  "allocation_percent": 100,
  "variants": [
    { "variant_id": "control", "name": "Original", "weight": 50, "is_control": true },
    { "variant_id": "redesign", "name": "New Flow", "weight": 50 }
  ]
}

Max 20 variants. config (optional JSON) max 4096 chars per variant.

Update experiment status. Sets started_at on transition to "active" and ended_at on "completed" or "archived".

{ "status": "draft" | "active" | "paused" | "completed" | "archived" }

Bot Management

List suspicious visitors. Returns aggregated metrics per visitor: max bot score, pageview count, devices, countries, exclusion status. limit max 200.

List all manually excluded visitors with pageview counts.

Exclude a visitor from rollups. Returns 201.

{ "visitor_id": "abc123", "label": "Known bot" }

Remove a visitor from the exclusion list.

{ "included": "abc123" }

Detailed visitor data: exclusion status, last 100 views, and last 100 events.

Performance Metrics

Query stored performance metrics. All params optional.

Ingest performance metrics (e.g. from CI/CD).

[{
  "category": "build",
  "metric": "bundle_size",
  "value": 142.5,
  "unit": "kb"
}]

Performance trends over time.

Sites

Get site settings (consent CSS).

Update site consent CSS (max 4096 chars).

Data Ingest

Bulk ingest visitor views and events. Max 1 MB body.

Error Responses

AGPL-3.0 — Copyright (C) 2026 Jani Tarvainen