TinyTrail API Documentation

API reference for TinyTrail — privacy-focused, cookie-less website analytics engine.

Base URL: http://localhost:8888 (default)

Table of Contents

• Authentication
• Response Format
• Error Codes
• Rate Limiting
• Endpoints
  • Health
  • Event Collection
  • Accounts
  • Users
  • Websites
  • Admin
  • Reports
    • Summary
    • Pages
    • Sources
    • Devices
    • Flow
    • Funnel
    • Realtime
    • Custom Events
    • Timeseries
    • Events (Raw)
  • Static Assets

Authentication

Protected endpoints require an API key passed via the X-API-KEY header.

X-API-KEY: your-api-key-here

Two roles exist:

Cross-account access by a user role returns 404 NOT_FOUND (not 403) to prevent resource enumeration.

Response Format

All endpoints use a consistent JSON envelope (except /health).

Success:

{
  "status": "success",
  "data": { ... }
}

Error:

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Codes

Rate Limiting

Rate-limited responses include a Retry-After header (seconds).

Endpoints

Health

GET /health

Health check for load balancers and uptime monitoring. No authentication required.

Response (200):

{
  "status": "ok",
  "db": "connected",
  "version": "0.1.0"
}

Response (503):

{
  "status": "degraded",
  "db": "disconnected"
}

Note: This endpoint does not use the standard response envelope.

Event Collection

OPTIONS /api/v1/collect

CORS preflight handler.

• Auth: None
• Response: 204 No Content
• Headers: Access-Control-Allow-Origin, Access-Control-Allow-Methods: POST, OPTIONS, Access-Control-Allow-Headers: Content-Type, Access-Control-Allow-Credentials: true, Vary: Origin

POST /api/v1/collect

Public event ingestion endpoint. No authentication required.

Accepts either a single event object or an array of events (batch mode, up to 100 events per request). A batch counts as a single request against the rate limiter.

• Auth: None
• Rate limit: 10 req / 10s per IP (a batch = 1 request)
• Content-Type: application/json

Request Body (single event):

Request Body (batch): A JSON array of event objects (each using the schema above). Maximum 100 events per request.

Default event types: page_view, close_tab, scroll_25, scroll_50, scroll_75, outbound_link, custom

Example (single event):

{
  "website_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "page_view",
  "url": "https://example.com/blog/post-1?utm_source=twitter",
  "path": "/blog/post-1",
  "referrer": "https://t.co/abc123",
  "screen_width": 1920,
  "screen_height": 1080
}

Example (batch):

[
  {
    "website_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "page_view",
    "url": "https://example.com/",
    "path": "/"
  },
  {
    "website_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "custom",
    "url": "https://example.com/pricing",
    "path": "/pricing",
    "custom_event_name": "signup_complete"
  }
]

Responses (single event):

Responses (batch):

Batch response body:

{
  "status": "success",
  "data": {
    "received": 2,
    "accepted": 1,
    "dropped": 1,
    "errors": 0,
    "results": [
      { "status": "accepted" },
      { "status": "dropped" }
    ]
  }
}

The results array preserves the order of the input events. Per-item status values:

• accepted — event was stored
• dropped — silently dropped (e.g. unknown website_id)
• error — event was rejected; the item also includes error: { code, message }

A batch with mixed accepted/dropped/error items still returns HTTP 200; inspect results for per-event outcomes.

Server-side processing pipeline:

1. Validate website_id exists (silent 204 drop if invalid)
2. Extract IP and User-Agent from request headers
3. Parse User-Agent → browser_family, os_family, device_type
4. Parse UTM parameters from url query string
5. Classify referrer → referrer_channel
6. Generate ip_hash = HMAC-SHA256(DailySalt, IP + UA + WebsiteID)
7. Check IP against website.excluded_ips → set is_excluded
8. Run bot detection → set is_bot
9. Match path against website.content_groups patterns
10. Store custom_event_name for custom events
11. Store event row

Accounts

All account endpoints require admin role.

GET /api/v1/accounts

List all accounts.

• Auth: Admin

Response (200):

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "name": "Acme Corp",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

POST /api/v1/accounts

Create a new account.

• Auth: Admin

Request Body:

Response (201):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Acme Corp",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Errors:

DELETE /api/v1/accounts/:id

Delete an account and all associated data (users, websites, events, aggregated data).

• Auth: Admin

Path Parameters:

Response (200): Deleted account object.

Errors:

Users

All user endpoints require admin role.

GET /api/v1/users

List all users (API key field excluded from response).

• Auth: Admin

Response (200):

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "accountId": "uuid",
      "email": "user@example.com",
      "role": "user",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

POST /api/v1/users

Create a new user. Returns the generated API key (only time it's shown).

• Auth: Admin

Request Body:

Response (201):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "email": "user@example.com",
    "role": "user",
    "apiKey": "tt_abc123...",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Errors:

GET /api/v1/users/:id/api-key

Retrieve a user's API key.

• Auth: Admin

Path Parameters:

Response (200):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "apiKey": "tt_abc123..."
  }
}

Errors:

DELETE /api/v1/users/:id

Delete a user.

• Auth: Admin

Path Parameters:

Response (200): Deleted user object.

Errors:

Websites

Website endpoints require authentication. Non-admin users are scoped to their own account.

GET /api/v1/websites

List websites. Admins see all; users see only their account's websites.

• Auth: User+

Response (200):

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "accountId": "uuid",
      "domain": "example.com",
      "contentGroups": [],
      "excludedIps": [],
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

POST /api/v1/websites

Create a new website.

• Auth: User+

Request Body:

Response (201): Created website object.

Errors:

PATCH /api/v1/websites/:id

Update website settings. At least one field must be provided.

• Auth: User+

Path Parameters:

Request Body:

Response (200): Updated website object.

Errors:

DELETE /api/v1/websites/:id

Delete a website and all associated events and aggregated data.

• Auth: User+

Path Parameters:

Response (200): Deleted website object.

Errors:

Admin

POST /api/v1/admin/aggregate

Manually trigger the aggregation pipeline for a specific date.

• Auth: Admin

Request Body:

Response (200):

{
  "status": "success",
  "data": {
    "message": "Aggregation completed for 2026-03-18"
  }
}

Errors:

Reports

All report endpoints require authentication and are scoped by account for non-admin users.

Common Query Parameters

When format=csv, the response uses Content-Type: text/csv with a Content-Disposition: attachment header.

Common Paginated Response Structure

{
  "status": "success",
  "data": {
    "period": { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" },
    "page": 1,
    "per_page": 50,
    "rows": [...]
  }
}

Common Errors (all report endpoints):

GET /api/v1/reports/summary

High-level metrics overview with optional period comparison.

• Auth: User+
• Extra params: compare (previous_period or yoy)

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "comparison": "2026-02-16 to 2026-02-22",
    "metrics": {
      "visits": { "value": 12450, "previous": 11200, "change_pct": 11.16 },
      "unique_pageviews": { "value": 9870, "previous": 8930, "change_pct": 10.53 },
      "pageviews": { "value": 34200, "previous": 30100, "change_pct": 13.62 },
      "bounce_rate": { "value": 42.3, "previous": 44.1, "change_pct": -4.08 },
      "avg_session_duration_sec": { "value": 185, "previous": 172, "change_pct": 7.56 }
    }
  }
}

When compare is not set, each metric contains only value (no previous or change_pct).

CSV columns: metric, value, previous, change_pct

GET /api/v1/reports/pages

Page-level traffic breakdown sorted by pageviews (descending).

• Auth: User+
• Paginated: Yes

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "page": 1,
    "per_page": 50,
    "rows": [
      {
        "path": "/blog/getting-started",
        "contentGroup": "Blog",
        "pageviews": 5420,
        "uniquePageviews": 3210
      }
    ]
  }
}

CSV columns: path, contentGroup, pageviews, uniquePageviews

GET /api/v1/reports/sources

Traffic source analysis with configurable grouping.

• Auth: User+
• Paginated: Yes

Extra Query Parameters:

Response — group_by=channel (200):

{
  "rows": [
    { "channel": "Organic Search", "visits": 4500 },
    { "channel": "Direct", "visits": 3200 },
    { "channel": "Social", "visits": 1800 }
  ]
}

Response — group_by=domain (200):

{
  "rows": [
    { "referrer": "google.com", "visits": 3200 },
    { "referrer": "twitter.com", "visits": 1100 }
  ]
}

Response — group_by=utm (200):

{
  "rows": [
    {
      "utmSource": "twitter",
      "utmMedium": "social",
      "utmCampaign": "launch",
      "visits": 850
    }
  ]
}

Referrer channel classifications:

GET /api/v1/reports/devices

Device, browser, and OS breakdown.

• Auth: User+
• Paginated: No

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "device_types": [
      { "deviceType": "desktop", "visits": 8500 },
      { "deviceType": "mobile", "visits": 3200 }
    ],
    "browsers": [
      { "browserFamily": "Chrome", "visits": 6400 },
      { "browserFamily": "Safari", "visits": 3100 }
    ],
    "os_families": [
      { "osFamily": "Windows", "visits": 5200 },
      { "osFamily": "macOS", "visits": 3800 }
    ],
    "screen_resolutions": [
      { "bucket": "1025-1440", "visits": 4200 },
      { "bucket": "376-768", "visits": 2800 }
    ]
  }
}

Screen resolution buckets: 320-375, 376-768, 769-1024, 1025-1440, 1441+, unknown

CSV columns: deviceType, visits (only device_types exported)

GET /api/v1/reports/flow

Landing and exit page analysis.

• Auth: User+
• Paginated: Yes (applies to both lists)

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "landing_pages": [
      { "path": "/", "entries": 5200 },
      { "path": "/blog", "entries": 2100 }
    ],
    "exit_pages": [
      { "path": "/pricing", "exits": 3400 },
      { "path": "/contact", "exits": 1800 }
    ]
  }
}

CSV columns: path, entries (only landing_pages exported)

GET /api/v1/reports/funnel

Multi-step conversion funnel analysis.

• Auth: User+

Extra Query Parameters:

Step patterns:

Example request:

GET /api/v1/reports/funnel?website_id=...&steps[]=/pricing&steps[]=event:user_signup&steps[]=/onboarding

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "funnel": [
      { "step": "/pricing", "sessions": 5000, "conversion_rate": 100 },
      { "step": "/signup", "sessions": 1200, "conversion_rate": 24.0 },
      { "step": "/onboarding", "sessions": 900, "conversion_rate": 75.0 }
    ]
  }
}

Conversion rate: First step is always 100%. Subsequent steps: (sessions at step N / sessions at step N-1) * 100, rounded to 2 decimals.

Session logic: Grouped by IP hash with a 30-minute gap threshold.

Errors:

GET /api/v1/reports/realtime

Real-time traffic for the last 30 minutes. Queries raw events table directly.

• Auth: User+
• Paginated: No

Query Parameters:

Response (200):

{
  "status": "success",
  "data": {
    "active_visitors": 42,
    "top_pages": [
      { "path": "/", "visitors": 18 },
      { "path": "/blog/new-post", "visitors": 12 }
    ],
    "events_by_type": [
      { "eventType": "page_view", "count": 87 },
      { "eventType": "scroll_50", "count": 34 }
    ]
  }
}

• Active visitors: Unique IP hashes in 30-minute window
• Top pages: Limited to top 10
• Filters: Excludes bot and excluded traffic

GET /api/v1/reports/custom-events

Custom event tracking and analysis.

• Auth: User+
• Paginated: Yes

Extra Query Parameters:

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-02-23", "end": "2026-03-01" },
    "page": 1,
    "per_page": 50,
    "rows": [
      {
        "name": "signup_complete",
        "count": 342,
        "paths": [
          { "path": "/pricing", "count": 210 },
          { "path": "/blog/getting-started", "count": 132 }
        ]
      },
      {
        "name": "video_play",
        "count": 218,
        "paths": [
          { "path": "/", "count": 150 },
          { "path": "/demos", "count": 68 }
        ]
      }
    ]
  }
}

Each row includes a paths array with per-path counts sorted by count descending.

CSV columns: name, count (flat totals only, no path breakdown)

GET /api/v1/reports/timeseries

Daily time-series data for a single metric over the selected period.

• Auth: User+
• Paginated: No

Extra Query Parameters:

Rate metrics (bounce_rate, avg_session_duration) are averaged per day. Count metrics are summed.

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-03-13", "end": "2026-03-19" },
    "metric": "pageviews",
    "path": "*",
    "series": [
      { "date": "2026-03-13", "value": 1200 },
      { "date": "2026-03-14", "value": 1350 },
      { "date": "2026-03-15", "value": 980 },
      { "date": "2026-03-16", "value": 870 },
      { "date": "2026-03-17", "value": 1100 },
      { "date": "2026-03-18", "value": 1420 },
      { "date": "2026-03-19", "value": 1290 }
    ]
  }
}

CSV columns: date, value

Errors:

GET /api/v1/reports/events

Raw event log for a given time range. Queries the events table directly.

• Auth: User+
• Paginated: Yes

Extra Query Parameters:

Response (200):

{
  "status": "success",
  "data": {
    "period": { "start": "2026-03-24", "end": "2026-03-30" },
    "page": 1,
    "per_page": 50,
    "rows": [
      {
        "id": "42",
        "eventType": "page_view",
        "url": "https://example.com/blog/post-1?utm_source=twitter",
        "path": "/blog/post-1",
        "referrer": "https://t.co/abc123",
        "referrerChannel": "Social",
        "utmSource": "twitter",
        "utmMedium": "social",
        "utmCampaign": "launch",
        "browserFamily": "Chrome",
        "osFamily": "macOS",
        "deviceType": "desktop",
        "screenWidth": 1920,
        "screenHeight": 1080,
        "isBot": false,
        "userUuid": null,
        "customEventName": null,
        "createdAt": "2026-03-30T14:22:01.000Z"
      }
    ]
  }
}

CSV columns: id, eventType, url, path, referrer, referrerChannel, utmSource, utmMedium, utmCampaign, browserFamily, osFamily, deviceType, screenWidth, screenHeight, isBot, userUuid, customEventName, createdAt

Static Assets

GET /

This API documentation, rendered as an HTML page (text/html; charset=utf-8). The raw markdown is served as text/markdown at GET /docs/api.md.

• Auth: None
• Cache-Control: public, max-age=3600 (1 hour)

GET /js/tracker.js

Client-side tracking snippet (vanilla JavaScript).

• Auth: None
• Rate limit: None
• Content-Type: application/javascript
• Cache-Control: public, max-age=86400 (24 hours)

Installation:

<script defer data-id="YOUR_WEBSITE_UUID" src="https://your-api.com/js/tracker.js"></script>

User identification:

Optionally associate events with a known user by setting data-uuid on the script tag or calling identify() after login:

<script defer data-id="YOUR_WEBSITE_UUID" data-uuid="USER_UUID" src="https://your-api.com/js/tracker.js"></script>

window.tinytrail.identify("user-abc-123");

The identify() call overrides data-uuid for all subsequent events in the session. The user_uuid field is optional and not used in aggregation.

SPA page views:

// Call after each client-side route change
window.tinytrail.pageview();

Sends a page_view event with the current URL and resets scroll depth tracking.

Custom events API:

window.tinytrail.track("signup_complete");

Auto-tracked events:

Endpoint Summary