openapi: 3.0.1
info:
  title: Counter Account Tracking API
  description: Counter (counter.dev) is an open-source, privacy-friendly web analytics service. This specification documents the real HTTP surface of the Counter server as implemented in the AGPL-3.0 source at https://github.com/ihucos/counter.dev. The tracking/collect endpoints are public and unauthenticated and are called by the browser tracking snippet. The stats endpoints return aggregated data and are protected either by a session cookie or by a user + token pair (sessionless, read-only). The account endpoints back the dashboard UI and are not a formally published developer API. Endpoint paths are derived directly from the server source; request/response schemas beyond the documented query parameters are not formally published by the project, so responses are described rather than fully schematized.
  termsOfService: https://counter.dev/
  contact:
    name: Counter (ihucos)
    url: https://github.com/ihucos/counter.dev
  license:
    name: AGPL-3.0
    url: https://github.com/ihucos/counter.dev/blob/master/LICENSE
  version: '1.0'
servers:
- url: https://t.counter.dev
  description: Default hosted tracking / collect host (configurable via data-server).
- url: https://counter.dev
  description: Hosted dashboard, stats, and account host. Self-hosted deployments use their own host.
tags:
- name: Tracking
paths:
  /track:
    get:
      operationId: track
      tags:
      - Tracking
      summary: Record an aggregated visit.
      description: Called by the tracking snippet ~4.5s after load, once per tab (guarded by a sessionStorage flag). Records a single aggregated visit for the site identified by the data-id. Requires an Origin header (used to derive the site id). No cookies are set and no IP address is stored; country may be supplied explicitly or derived from the CF-IPCountry header. Bots and localhost origins are ignored.
      parameters:
      - name: id
        in: query
        description: Site data-id (per-account cached UUID). Either id, user, or site must be provided.
        required: false
        schema:
          type: string
      - name: user
        in: query
        description: Account user id, used when id is not supplied.
        required: false
        schema:
          type: string
      - name: site
        in: query
        description: Legacy alias for the user/account id, supported for backward compatibility.
        required: false
        schema:
          type: string
      - name: referrer
        in: query
        description: Document referrer URL; only the host is retained.
        required: false
        schema:
          type: string
      - name: screen
        in: query
        description: Screen resolution as WIDTHxHEIGHT (bucketed to known resolutions or "Other").
        required: false
        schema:
          type: string
      - name: utcoffset
        in: query
        description: Client UTC offset, used to bucket the visit into the correct local day/hour.
        required: false
        schema:
          type: string
      - name: country
        in: query
        description: Two-letter country code; if omitted the CF-IPCountry header is used.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Visit recorded. Body is the plain text "OK".
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request - missing site identifier or missing/invalid Origin header.
  /trackpage:
    post:
      operationId: trackpage
      tags:
      - Tracking
      summary: Record a pageview.
      description: Called by the tracking snippet via the browser Beacon API on every page load to record a pageview counter for the given path. Requires an Origin header. Body is application/x-www-form-urlencoded.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Site data-id (per-account cached UUID).
                page:
                  type: string
                  description: Page path (window.location.pathname).
      responses:
        '204':
          description: Pageview recorded. Empty body.
        '400':
          description: Bad request - missing or invalid Origin header.
components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie set on login/register, used by the dashboard UI.
    apiToken:
      type: apiKey
      in: query
      name: token
      description: Read-only account token, paired with the user query parameter, for sessionless access to /query and /dump.