# Webcounter.ca

> Privacy-respecting web analytics. This guide introduces the API to an
> automated client that already has a Counter key.

## Authentication

Two kinds of bearer key, sent as `Authorization: Bearer <key_id>.<secret>`,
never a query string:

- `ctr_...` — an API key. Read-only.
- `ctr_mgmt_...` — a secret key. Read and write: sites, goals, share links,
  scheduled reports, data exports, and other keys.

Account settings, uptime monitoring, and Web Push require a signed-in browser
session and do not accept bearer keys.

## Docs

- [API documentation](/docs) — human-readable, start here.
- [OpenAPI 3.1 contract](/static/openapi.yaml) — full machine-readable spec:
  every path, parameter, request/response schema, and which routes require
  a secret key versus either kind.
- [Help center](/help) — installation, consent, and troubleshooting for the
  tracking snippet itself (not the API).

## Conventions

- Every response is `{"ok": true, "data": {...}}` or
  `{"ok": false, "error": {"code": "...", "message": "..."}}`. The HTTP
  status is authoritative.
- Analytics reads take `range` (`today`, `7d`, `30d`, `90d`, `6mo`, `12mo`)
  or paired `start`/`end` ISO-8601 values; ranges are half-open.
- Visitor/map feeds paginate with an opaque `next_cursor` — pass it back
  unchanged, stop when `has_more` is false.
- A listed resource identifies itself with `id`; the path parameter that
  consumes it is named after the resource (`GET /api-keys` rows carry `id`,
  `DELETE /api-keys/{key_id}` takes that same value). Do not look for a
  `key_id` field in a response — there isn't one.
- Timestamps are ISO-8601 with a `+00:00` offset, except on the four
  per-visit reads (`/realtime`, `/visitors`, `/visitor-map`,
  `/session/{id}`), which return RFC 1123 HTTP-dates. The contract marks
  those fields `HttpDate`.