# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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](/content/docs/mcp-server/index.html) uses the same tokens and gives AI tools direct access to your analytics data.

[Manage API tokens](/content/settings/api-tokens/index.html)