API reference

POST/api/ev

Send an eventNo key, or a write key

The one endpoint every collector writes to: the browser tag and your own server code both POST this shape.

Two modes share the URL. With no Authorization header it is browser mode: the site is resolved from d, and the visitor IP and user-agent are read from the request itself. With Authorization: Bearer sk_... (a write-scoped key) it is server-side mode: the site is resolved from the key, and you relay the end user ip and ua yourself. Omit those two and every server-side event is attributed to your server — one visitor, all day.

Send the body as Content-Type: text/plain. That is deliberate: it keeps the browser request a CORS simple request, with no preflight round-trip. The server reads the body as text and parses JSON either way, so application/json also works from a server.

Identity is always derived server-side. No field lets a caller claim a visitor id, a session or a collector.

Request body

A JSON object, serialized as text. Content-Type: text/plain

Example

curl -i -X POST "https://causalit.fr/api/ev"   -H "Authorization: Bearer $CAUSALIT_WRITE_KEY"   -H "Content-Type: text/plain"   --data '{"d":"example.com","n":"signup","u":"https://example.com/signup","p":{"plan":"pro"},"ip":"203.0.113.7","ua":"Mozilla/5.0 (...)"}'

Responses

GET/api/v1/summary

Headline metricsRead key

The five numbers at the top of the dashboard, for the selected range and filters.

Parameters

Example

curl -s "https://causalit.fr/api/v1/summary?period=30d"   -H "Authorization: Bearer $CAUSALIT_READ_KEY"

Responses

{
  "meta": {
    "site": "example.com",
    "period": "7d",
    "start": "2026-08-17T00:00:00.000Z",
    "end": "2026-08-24T00:00:00.000Z",
    "granularity": "day"
  },
  "summary": {
    "visitors": 1234,
    "pageviews": 4567,
    "sessions": 1500,
    "bounceRate": 42,
    "avgDurationSec": 95
  }
}

GET/api/v1/timeseries

Visitors and pageviews over timeRead key

One row per bucket. The bucket size follows the period unless gran overrides it, and is always stated in meta.granularity: hourly for day, monthly for a full year, daily otherwise. Empty buckets come back as zeros rather than being skipped.

Parameters

Example

curl -s "https://causalit.fr/api/v1/timeseries?period=7d"   -H "Authorization: Bearer $CAUSALIT_READ_KEY"

Responses

{
  "meta": {
    "site": "example.com",
    "period": "7d",
    "start": "2026-08-17T00:00:00.000Z",
    "end": "2026-08-24T00:00:00.000Z",
    "granularity": "day"
  },
  "series": [
    {
      "bucket": "2026-08-17",
      "visitors": 120,
      "pageviews": 340
    },
    {
      "bucket": "2026-08-18",
      "visitors": 143,
      "pageviews": 402
    }
  ]
}

GET/api/v1/breakdown/{dim}

Top values for one dimensionRead key

The dashboard tables — top pages, sources, countries, devices — as JSON, ordered by visitors.

Paths come back as grouped routes, not raw URLs: /orders/4412 and /orders/4413 are one row, spelled the way this site path grouping is configured.

Every dimension the dashboard tables cover is available here: path, source, country, region, city, browser, os, device, utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer.

Parameters

Example

curl -s "https://causalit.fr/api/v1/breakdown/source?period=30d&limit=10"   -H "Authorization: Bearer $CAUSALIT_READ_KEY"

Responses

{
  "meta": {
    "site": "example.com",
    "period": "7d",
    "start": "2026-08-17T00:00:00.000Z",
    "end": "2026-08-24T00:00:00.000Z",
    "granularity": "day",
    "dimension": "source"
  },
  "rows": [
    {
      "key": "google",
      "visitors": 300,
      "pageviews": 480
    },
    {
      "key": "direct",
      "visitors": 210,
      "pageviews": 265
    }
  ]
}

GET/api/v1/goals

Conversions per goalRead key

Every goal defined on the site, active or not, with its conversions for the range. A goal that never fired is returned with zeros — the list is the site configuration, not only what happened.

Parameters

Example

curl -s "https://causalit.fr/api/v1/goals?period=30d"   -H "Authorization: Bearer $CAUSALIT_READ_KEY"

Responses

{
  "meta": {
    "site": "example.com",
    "period": "7d",
    "start": "2026-08-17T00:00:00.000Z",
    "end": "2026-08-24T00:00:00.000Z",
    "granularity": "day"
  },
  "goals": [
    {
      "id": "0f2c1a7e-...",
      "name": "Signup",
      "kind": "path",
      "pattern": "/welcome",
      "active": true,
      "conversions": 42,
      "visitors": 40,
      "rate": 3.5,
      "value": 0
    }
  ]
}

GET/api/sites/{id}/export

Download stats as CSVRead key or session

The same aggregates as the read API, as a CSV attachment (UTF-8 with a BOM, so spreadsheets read accents correctly).

The only endpoint that takes a site id in the URL, because the dashboard export buttons call it with your session. With a key, the key must belong to that site.

Parameters

Example

curl -sL "https://causalit.fr/api/sites/SITE_ID/export?type=breakdown&dim=source&period=30d"   -H "Authorization: Bearer $CAUSALIT_READ_KEY" -o sources.csv

Responses

{
  "error": "This key is not authorized for this site."
}