API Documentation

Connect any stack to LyticData. API key required. Create a project to get your key.

Supported stacks: Next.js (App + Pages), React, Vue, Vanilla HTML/JS — plus a REST API any backend can call (Python, Ruby, Go, PHP, Rust, .NET…).

1. Get your API key

Go to Dashboard → Add Project → Create new project. Copy the API key — it's shown once on creation. If you lose it, paste it back via Add existing API key on the same screen.

2. Next.js (recommended)

best fit

The Next.js helper auto-tracks API routes and server work (method, route, status, duration, server-side errors) in addition to client-side pageviews. Two pieces — middleware for server tracking, script tag for client tracking.

a) Download the helper into your project

Save it as lib/lyticdata.js in your Next.js repo. (Not on npm yet — single-file install.)

curl http://localhost:3000/api/helpers/nextjs -o lib/lyticdata.js

Or open http://localhost:3000/api/helpers/nextjs and save the file.

b) Set env vars

# .env.local
LYTICDATA_URL=http://localhost:3000
LYTICDATA_API_KEY=YOUR_API_KEY

c) Wrap your middleware (server-side tracking)

// middleware.js (project root)
import { withLyticData } from './lib/lyticdata';

export default withLyticData(); // or withLyticData(yourExistingMiddleware)

export const config = {
  // exclude static assets
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

d) Add the client script (click map + UTM + client errors)

// app/layout.js
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script id="lyticdata-config" strategy="beforeInteractive">
          {`window.LYTICDATA_CONFIG = { api: "http://localhost:3000", apiKey: "YOUR_API_KEY" };`}
        </Script>
        <Script src="http://localhost:3000/lyticdata.js" strategy="afterInteractive" />
      </body>
    </html>
  );
}

e) Track server-side events (purchases, signups, cron jobs)

import { trackServer } from './lib/lyticdata';

// After Stripe webhook fires:
await trackServer({
  type: 'event',
  name: 'purchase',
  revenue: 29,
  currency: 'USD',
  clerkId: user.id,
  metadata: { plan: 'pro' },
});

3. React / Vue / Vanilla HTML

Drop two script tags before </body>. Auto-tracks pageviews, UTM, time-on-page, click map (which elements were clicked), scroll depth, and uncaught errors.

<script>
  window.LYTICDATA_CONFIG = {
    api: "http://localhost:3000",
    apiKey: "YOUR_API_KEY",
    clickMap: true,          // default true — records which elements were clicked
    requireConsent: false,   // set true to hold tracking until grantConsent()
    // userId — optional OPAQUE reference (e.g. a hash of your user id) so you can
    // correlate behavior on your side. Never send names or emails: by design,
    // LyticData stores no end-user PII and ignores any name/email fields.
  };
</script>
<script src="http://localhost:3000/lyticdata.js" async></script>

4. Custom events

After the script loads, call window.LyticData.track() from anywhere.

window.LyticData.track('signup_started', { plan: 'pro' });
window.LyticData.track('purchase', { revenue: 29, currency: 'USD' });
window.LyticData.track('feature_used', { feature: 'export_csv' });

Event names containing "purchase", "order", "checkout", "payment", or "sale" (or any event with a revenue field) trigger a payment notification.

5. Track Errors

The script captures uncaught errors and unhandled promise rejections automatically. To send a caught error manually:

try {
  await doRiskyThing();
} catch (err) {
  window.LyticData.captureError(err);
}

6. REST API — any backend

Anything that can make an HTTPS request can send events. CORS is open; auth is a single header.

POST an event

POST http://localhost:3000/api/events
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "type": "event",
  "name": "purchase",
  "revenue": 29,
  "currency": "USD",
  "url": "https://yoursite.com/checkout",
  "path": "/checkout",
  "visitorId": "user-123",
  "clerkId": "user_abc123",
  "metadata": { "plan": "pro" }
}

curl

curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"type":"event","name":"signup","clerkId":"user_abc"}'

Python (requests)

import requests

requests.post(
    "http://localhost:3000/api/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "event",
        "name": "purchase",
        "revenue": 29,
        "currency": "USD",
        "clerkId": user.id,
    },
)

POST an error

POST http://localhost:3000/api/errors
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "message": "Stripe webhook signature mismatch",
  "stack": "...",
  "url": "https://yoursite.com/api/webhooks/stripe",
  "metadata": { "stripeEventId": "evt_..." }
}

7. Privacy & consent

no PII stored

LyticData stores no end-user names, emails, or raw IP addresses — visitors are tracked by a random anonymous ID, location is country/city only, and raw data is deleted after 90 days. See the Privacy Policy and DPA.

Consent gate

Set requireConsent: true and nothing is tracked until you grant consent (e.g. from your cookie banner's "Accept" handler):

// After the visitor accepts:
window.LyticData.grantConsent();
// To stop again:
window.LyticData.revokeConsent();

Erase a user (right to erasure)

Delete all of one end-user's data within your project. Call this from your backend when a user requests deletion.

POST http://localhost:3000/api/erase
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "visitorId": "the-anonymous-id", "externalId": "your-user-ref" }

Export / delete a whole project

From the dashboard project switcher: Export downloads all of a project's data as JSON; Delete data permanently erases it and disconnects the project.

8. Read your data (GET)

Fetch aggregated events or recent errors. Useful for your own dashboards or alerts.

GET http://localhost:3000/api/events?days=7&type=pageview
X-API-Key: YOUR_API_KEY

GET http://localhost:3000/api/errors?days=7&limit=50&resolved=false
X-API-Key: YOUR_API_KEY