API Reference

REST API

Programmatically access your analytics data. All endpoints require a Bearer API token, which you can generate from your account settings.

Base URL

Prefix all endpoint paths with this base URL:

https://ghostlyx.com/api/v1

Authentication

Pass your API token as a Bearer header:

Authorization: Bearer <YOUR_API_TOKEN>

GET /sites List sites

Returns all sites you own and sites you are a member of.

Example

curl -H "Authorization: Bearer TOKEN" \
  https://ghostlyx.com/api/v1/sites

GET /sites/{domain}/stats Site statistics

Returns aggregate analytics data for a site over a given period.

Query parameters

period string One of: 24h, 7d, 30d, 6mo, 12mo. Default: 30d optional

Example

curl -H "Authorization: Bearer TOKEN" \
  "https://ghostlyx.com/api/v1/sites/example.com/stats?period=30d"

GET /sites/{domain}/pages Top pages

Returns the top pages for a site, ordered by pageview count.

Query parameters

period string One of: 24h, 7d, 30d, 6mo, 12mo. Default: 30d optional

limit integer Number of results, max 50. Default: 10 optional

Example

curl -H "Authorization: Bearer TOKEN" \
  "https://ghostlyx.com/api/v1/sites/example.com/pages?period=7d&limit=10"

GET /sites/{domain}/referrers Top referrers

Returns the top traffic sources for a site, ordered by visit count.

Query parameters

period string One of: 24h, 7d, 30d, 6mo, 12mo. Default: 30d optional

limit integer Number of results, max 50. Default: 10 optional

Example

curl -H "Authorization: Bearer TOKEN" \
  "https://ghostlyx.com/api/v1/sites/example.com/referrers?period=7d"

GET /sites/{domain}/realtime Realtime visitors

Returns the number of unique visitors active on the site in the last 5 minutes.

Example

curl -H "Authorization: Bearer TOKEN" \
  https://ghostlyx.com/api/v1/sites/example.com/realtime

POST /collect/pageview Record a pageview

Send a pageview from your backend. Requires a token with the collect:write ability and a Business plan or above. Pass the real visitor IP and User-Agent for accurate geo and device data.

Request body (JSON)

tracking_id string Site tracking ID (gx_XXXXXXXXXXXX)

url string Full page URL. Query strings and fragments are stripped.

pathname string Path component of the URL, e.g. /blog/post.

referrer string Referrer URL if known. optional

ip string Visitor IP. Hashed with a daily salt into an anonymous visitor fingerprint and used for geo lookup, then discarded. The raw IP is never written to the database. optional

user_agent string Visitor User-Agent. Parsed for browser and device detection, then discarded. The raw string is never stored. optional

utm_source string UTM source parameter. optional

utm_medium string UTM medium parameter. optional

utm_campaign string UTM campaign parameter. optional

timestamp integer Unix timestamp (seconds). Defaults to current server time. optional

Example

curl -X POST -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tracking_id":"gx_abc123","url":"https://example.com/blog/post","pathname":"/blog/post","ip":"203.0.113.42"}' \
  https://ghostlyx.com/api/v1/collect/pageview

POST /collect/event Record a custom event

Send a named custom event from your backend. Requires a token with the collect:write ability and a Business plan or above.

Request body (JSON)

tracking_id string Site tracking ID (gx_XXXXXXXXXXXX)

name string Event name, e.g. "Signup" or "Purchase". Max 255 characters.

url string Full URL of the page where the event occurred.

pathname string Path component of the URL.

props object Flat key-value metadata. Max 4 KB. Do not include personal data. optional

ip string Visitor IP. Hashed with a daily salt into an anonymous visitor fingerprint and used for geo lookup, then discarded. The raw IP is never written to the database. optional

user_agent string Visitor User-Agent. Parsed for browser and device detection, then discarded. The raw string is never stored. optional

timestamp integer Unix timestamp (seconds). Defaults to current server time. optional

Example

curl -X POST -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tracking_id":"gx_abc123","name":"Signup","url":"https://example.com/register","pathname":"/register","props":{"plan":"growth"}}' \
  https://ghostlyx.com/api/v1/collect/event

Need an API token? Generate one from your account settings.

Looking for AI assistant integration? The MCP server uses the same tokens and gives AI tools direct access to your analytics data.

Manage API tokens