# Analytics REST API

> The Privatus Analytics REST API: add .json to any app URL and send a token. Conventions and a reference of every operation, generated from the code.

Every page and action in Privatus Analytics is also an API endpoint. There's no
separate `/api/v1`: **add `.json` to a URL** and send an API token.

```sh
curl https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=7d \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"
```

```json
{
  "data": {
    "period": { "from": "2026-09-23T00:00:00Z", "to": "2026-09-30T00:00:00Z" },
    "metrics": {
      "visitors": 1840, "visits": 2310, "pageviews": 5122,
      "views_per_visit": 2.22, "bounce_rate": 41.3,
      "visit_duration": 48000, "revenue": 129900
    }
  }
}
```

The [reference below](#operations) lists every operation with its method,
path, permission, input schema and response schema. It's generated from
the running code, as is the **[OpenAPI 3.1 document](/openapi.json)**, so
neither can drift from what the server does. The same operations are
[MCP tools](/docs/mcp).

## Conventions

| | |
|---|---|
| Base URL | `https://privatusanalytics.com` |
| Format | JSON. Add `.json` to the path (or send `Accept: application/json`) |
| Auth | `Authorization: Bearer pat_…` ([Authentication](/docs/api/authentication)) |
| Ids | Public ids with a prefix: `ws_…` workspaces, `pa_…` sites, `seg_…` segments, `wh_…` webhooks |
| Reads | `GET` with query parameters |
| Writes | `POST`, `PATCH`, `DELETE` with a JSON body of flat fields |
| Success | `{ "data": … }`, plus `"meta"` for lists |
| Errors | `{ "error": { "code", "message", "details" } }` ([Errors](/docs/api/errors)) |
| Lists | `page` and `per_page` (max 100) ([Pagination](/docs/api/pagination)) |
| Times | ISO 8601 in UTC. Date parameters (`from`, `to`) are days in the site's timezone |
| Money | Minor units (cents) in the site currency, e.g. `revenue: 129900` = 1,299.00 |
| Durations | Milliseconds |

## Common tasks

| Task | Operation |
|---|---|
| List workspaces | `GET /workspaces.json` |
| List sites | `GET /workspaces/{workspace_id}/sites.json` |
| Headline metrics | `GET /sites/{site_id}/stats/aggregate.json` |
| Chart data | `GET /sites/{site_id}/stats/timeseries.json` |
| Top pages, sources, countries… | `GET /sites/{site_id}/breakdown/{dimension}.json` |
| Everything on the Overview | `GET /sites/{site_id}/overview.json` |
| Live visitors | `GET /sites/{site_id}/live.json` |
| Add a note (e.g. a deploy) | `POST /sites/{site_id}/notes.json` |

See [Stats endpoints](/docs/api/stats) and [Examples](/docs/api/examples).

## In this section

[Authentication](/docs/api/authentication) · [Errors](/docs/api/errors) ·
[Pagination](/docs/api/pagination) · [Rate limits](/docs/api/rate-limits) ·
[Filters](/docs/api/filters) · [Stats endpoints](/docs/api/stats) ·
[Examples](/docs/api/examples) · [Webhooks](/docs/api/webhooks) ·
[Changelog and deprecation](/docs/api/changelog)

Sending data in is a different API: see [Server-side ingest](/docs/server-side).