REST API

Two halves: an ingestion endpoint for sending events, and read endpoints for pulling your own numbers back out. Every endpoint, every field and every status code is listed in the API reference — this guide is the orientation.

One base URL

Everything answers on https://causalit.fr. There is no API subdomain: a request to any other hostname resolves elsewhere, or nowhere, and never reaches your account. If you proxy ingestion first-party, your own domain is the exception — but only for /api/ev.

Sending events

POST to /api/ev. From a browser the tag does this for you. From a server, authenticate with a write-scoped API key and relay the visitor’s IP and user agent so the fingerprint is computed from the real visitor rather than from your server.

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

Send the body as text/plain: that keeps a browser request free of a CORS preflight, and the server parses JSON either way. `u` must be an absolute URL, scheme included — a bare path is the single most common 400.

Reading data

Read endpoints need a read-scoped key and return the same aggregates the dashboard shows: /api/v1/summary, /api/v1/timeseries, /api/v1/breakdown/{dimension} and /api/v1/goals, plus a CSV export. The key resolves the site, so you never pass a site id.

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

Keys

• A key is shown once, at creation. We store only its hash — we cannot show it to you again, and neither can anyone who reaches our database.
• A key carries one scope, chosen at creation and fixed: a write key ingests and gets 403 on a read endpoint; a read key reads and gets 401 on ingestion.
• Revoking a key takes effect immediately.
• Use a write key on your servers and a read key in whatever pulls reports. Never ship either to a browser.

When nothing arrives

• Send the request with curl -i and read the status: with a bearer token the endpoint is explicit — 202 accepted, 400 malformed payload, 401 key problem, 402 monthly quota spent. Only browser mode is silent.
• Check the host character for character: https://causalit.fr/api/ev.
• Check the scope: ingestion rejects a read-scoped key exactly as it rejects an unknown one.
• Then look at "Last used" beside the key in Site → Settings → API keys. If it is still empty, no authenticated request ever reached us — the problem is the URL, the header or the network, not the body.