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>

Endpoints

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.

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