openapi: 3.0.3
info:
  title: Medama Analytics API
  version: 0.1.0
  description: |
    This is the Medama Analytics OpenAPI 3.0 specification.
  contact:
    email: hello@ayuhito.com
    name: Medama Analytics
    url: https://medama.io/contact
  license:
    url: "https://github.com/ayuhito/medama/blob/main/core/LICENSE"
    name: Apache License 2.0
servers:
  - url: "http://localhost:8080"
    description: Local Server
tags:
  - name: auth
    description: Authentication
  - name: event
    description: Page Events
  - name: user
    description: User Management
  - name: website
    description: Website Management
  - name: stats
    description: Statistics
paths:
  /auth/login:
    post:
      tags:
        - auth
      summary: Session Token Authentication.
      description: Login to the service and retrieve a session token for authentication.
      operationId: post-auth-login
      requestBody:
        description: Login details.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthLogin"
        required: true
      responses:
        "200":
          description: Success
          headers:
            Set-Cookie:
              schema:
                type: string
              description: Set the cookie for the session.
              required: true
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  /event/hit:
    post:
      tags:
        - event
      summary: Send Hit Event.
      description: Send a hit event to register a user view.
      operationId: post-event-hit
      parameters:
        - name: User-Agent
          in: header
          schema:
            type: string
          description: Used to infer user browser, OS and device.
        - name: Accept-Language
          in: header
          description: Used to infer user language.
          schema:
            type: string
      requestBody:
        description: Hit event metadata.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventHit"
        required: true
      responses:
        "204":
          description: OK.
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  /event/ping:
    get:
      tags:
        - event
      summary: Unique User Check.
      description: This is a ping endpoint to determine if the user is unique or not.
      operationId: get-event-ping
      parameters:
        - name: If-Modified-Since
          in: header
          description: If this exists, then user exists in cache and is not a unique user.
          schema:
            type: string
        - name: u
          in: query
          description: Optional query parameter that is the current host and pathname of the page.
          schema:
            type: string
      responses:
        "200":
          description: OK
          headers:
            Last-Modified:
              schema:
                type: string
              description: This is date of the current day from midnight, incremented by each page view by unique user.
              required: true
            Cache-Control:
              schema:
                type: string
              description: This is set to 1 day to prevent the user from being counted as a unique user again.
              required: true
            Access-Control-Allow-Origin:
              schema:
                type: string
              description: This is set to allow all origins to access this endpoint.
              required: true
            Access-Control-Allow-Methods:
              schema:
                type: string
              description: This is set to allow GET methods to access this endpoint.
              required: true
            Access-Control-Allow-Headers:
              schema:
                type: string
              description: This is set to allow If-Modified-Since headers and Content-Type headers to access this endpoint.
              required: true
          content:
            text/plain:
              schema:
                description: This is set to 0 if the user is a unique user, otherwise 1.
                type: string
                example: "0"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  /user:
    get:
      tags:
        - user
      security:
        - CookieAuth: []
      summary: Get User Info.
      description: Retrieve the information of the user with the matching user ID.
      operationId: get-user
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
      responses:
        "200":
          description: User Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGet"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
    patch:
      tags:
        - user
      security:
        - CookieAuth: []
      summary: Update User Info.
      description: Update a user account's details.
      operationId: patch-user
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
      requestBody:
        description: User details to update.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserPatch"
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGet"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
    delete:
      tags:
        - user
      security:
        - CookieAuth: []
      summary: Delete User.
      description: Delete a user account.
      operationId: delete-user
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
      responses:
        "200":
          description: Success
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  /websites:
    get:
      tags:
        - website
      security:
        - CookieAuth: []
      summary: List Websites.
      description: Get a list of all websites from the user.
      operationId: get-websites
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
      responses:
        "200":
          description: Returns a list of websites.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebsiteGet"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
    post:
      tags:
        - website
      security:
        - CookieAuth: []
      summary: Add Website.
      description: Add a new website.
      operationId: post-websites
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebsiteCreate"
        required: true
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteGet"
          links:
            GetWebsite:
              operationId: get-websites-id
              parameters:
                hostname: $response.body#/hostname
            PatchWebsite:
              operationId: patch-websites-id
              parameters:
                hostname: $response.body#/hostname
            DeleteWebsite:
              operationId: delete-websites-id
              parameters:
                hostname: $response.body#/hostname
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  "/websites/{hostname}":
    get:
      tags:
        - website
      security:
        - CookieAuth: []
      summary: Get Website.
      description: Get website details for an individual website.
      operationId: get-websites-id
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteGet"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
    patch:
      tags:
        - website
      security:
        - CookieAuth: []
      summary: Update Website.
      description: Update a website's information.
      operationId: patch-websites-id
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
      requestBody:
        description: Website details to update.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebsitePatch"
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteGet"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
    delete:
      tags:
        - website
      security:
        - CookieAuth: []
      summary: Delete Website.
      description: Delete a website.
      operationId: delete-websites-id
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
      responses:
        "200":
          description: Success
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  "/website/{hostname}/summary":
    get:
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Stat Summary.
      description: Get a summary of the website's stats.
      operationId: get-website-id-summary
      parameters:
        - in: query
          name: previous
          description: Retrieve the data from the previous period as well. This is useful when comparing data from the previous period to the current period. Requires the start and end period parameters to be set.
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsSummary"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  "/website/{hostname}/pages":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Page Stats.
      description: Get a list of pages and their stats.
      operationId: get-website-id-pages
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/Summary"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsPages"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  "/website/{hostname}/time":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Time Stats.
      description: Get a list of pages and their time stats.
      operationId: get-website-id-time
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/Summary"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsTime"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
      servers:
        - url: "http://localhost:8080"
          description: Local Server
  "/website/{hostname}/referrers":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Referrer Stats.
      description: Get a list of referrers and their stats.
      operationId: get-website-id-referrers
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/Summary"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsReferrers"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/sources":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get UTM Source Stats.
      description: Get a list of UTM sources and their stats.
      operationId: get-website-id-sources
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsUTMSources"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/mediums":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get UTM Medium Stats.
      description: Get a list of UTM mediums and their stats.
      operationId: get-website-id-mediums
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsUTMMediums"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/campaigns":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get UTM Campaign Stats.
      description: Get a list of UTM campaigns and their stats.
      operationId: get-website-id-campaigns
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsUTMCampaigns"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/browsers":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Browser Stats.
      description: Get a list of browsers and their stats.
      operationId: get-website-id-browsers
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsBrowsers"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/os":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get OS Stats.
      description: Get a list of OS and their stats.
      operationId: get-website-id-os
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsOS"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/devices":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Device Stats.
      description: Get a list of devices and their stats.
      operationId: get-website-id-device
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsDevices"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/countries":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Country Stats.
      description: Get a list of countries and their stats.
      operationId: get-website-id-country
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsCountries"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/website/{hostname}/languages":
    "get":
      tags:
        - stats
      security:
        - CookieAuth: []
      summary: Get Language Stats.
      description: Get a list of languages and their stats.
      operationId: get-website-id-language
      parameters:
        - $ref: "#/components/parameters/SessionAuth"
        - $ref: "#/components/parameters/Hostname"
        - $ref: "#/components/parameters/PeriodStart"
        - $ref: "#/components/parameters/PeriodEnd"
        - $ref: "#/components/parameters/PeriodInterval"
        - $ref: "#/components/parameters/Path"
        - $ref: "#/components/parameters/Referrer"
        - $ref: "#/components/parameters/UTMSource"
        - $ref: "#/components/parameters/UTMMedium"
        - $ref: "#/components/parameters/UTMCampaign"
        - $ref: "#/components/parameters/Browser"
        - $ref: "#/components/parameters/OS"
        - $ref: "#/components/parameters/Device"
        - $ref: "#/components/parameters/CountryCode"
        - $ref: "#/components/parameters/Language"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsLanguages"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorisedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  securitySchemes:
    CookieAuth:
      name: _me_sess
      in: cookie
      type: apiKey
      description: Session token for authentication.
  parameters:
    # Authentication
    SessionAuth:
      name: _me_sess
      in: cookie
      description: Session token for authentication.
      required: true
      schema:
        type: string
        example: _me_sess=token; Path=/; HttpOnly; Secure; SameSite=Strict
    Hostname:
      name: hostname
      in: path
      description: Hostname for the website.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 253 # FQDN limit
        format: hostname
    Summary:
      name: summary
      in: query
      description: Return a summary of the stats.
      required: false
      schema:
        type: boolean
        default: false
    # Filters
    Path:
      name: path
      in: query
      description: Path of the page.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterString"
    Referrer:
      name: referrer
      in: query
      description: Referrer URL of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterString"
    UTMSource:
      name: utm_source
      in: query
      description: UTM source of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterString"
    UTMMedium:
      name: utm_medium
      in: query
      description: UTM medium of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterString"
    UTMCampaign:
      name: utm_campaign
      in: query
      description: UTM campaign of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterString"
    Browser:
      name: browser
      in: query
      description: Browser name.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterFixed"
    OS:
      name: os
      in: query
      description: Operating system name.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterFixed"
    Device:
      name: device
      in: query
      description: Device type.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterFixed"
    CountryCode:
      name: country
      in: query
      description: Country code.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterFixed"
    Language:
      name: language
      in: query
      description: Language code.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: "#/components/schemas/FilterFixed"
    PeriodStart:
      name: start
      in: query
      description: Period start date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
      required: false
      schema:
        type: string
        format: date-time
    PeriodEnd:
      name: end
      in: query
      description: Period end date using fdate-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
      required: false
      schema:
        type: string
        format: date-time
    PeriodInterval:
      name: interval
      in: query
      description: Period interval.
      required: false
      schema:
        type: string
        enum:
          - hour
          - day
          - week
          - month
          - year
    Limit:
      name: limit
      in: query
      description: Limit the number of results.
      schema:
        type: integer
        minimum: 1
        maximum: 5000
    Offset:
      name: offset
      in: query
      description: Offset the results paired with the limit parameter.
      schema:
        type: integer
        minimum: 0
        maximum: 5000
  responses:
    BadRequestError:
      description: 400 Bad Request.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 400
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error
    UnauthorisedError:
      description: 401 Unauthorised.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 401
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error
    ForbiddenError:
      description: 403 Forbidden.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 403
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error
    NotFoundError:
      description: 404 Not Found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 404
                  message:
                    type: string
                required:
                  - code
                  - message

            required:
              - error
    ConflictError:
      description: 409 Conflict Found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 409
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error
    InternalServerError:
      description: 500 Unexpected Internal Server Error.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 500
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error
  schemas:
    AuthLogin:
      type: object
      title: AuthLogin
      description: Request body for logging in.
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 120
        password:
          type: string
          minLength: 5
          maxLength: 128
          format: password
      required:
        - username
        - password
    EventLoad:
      title: EventLoad
      description: Page view load event.
      type: object
      properties:
        b:
          type: string
          description: Beacon ID generated for each user to link multiple events on the same page together.
        u:
          type: string
          description: Page URL including query parameters.
          format: uri
        r:
          type: string
          description: Referrer URL.
        p:
          type: boolean
          description: If the user is a unique user or not.
        q:
          type: boolean
          description: If the user has visited this page before or not.
        t:
          type: string
          description: Timezone of the user.
      required:
        - b
        - u
        - p
        - q
    EventUnload:
      title: EventUnload
      description: Page view unload event.
      type: object
      properties:
        b:
          type: string
          description: Beacon ID generated for each user to link multiple events on the same page together.
        m:
          type: integer
          description: Time spent on page in milliseconds.
      required:
        - b
        - m
    EventHit:
      title: EventHit
      description: Website hit event.
      oneOf:
        - $ref: "#/components/schemas/EventLoad"
        - $ref: "#/components/schemas/EventUnload"
      discriminator:
        propertyName: e
        mapping:
          load: "#/components/schemas/EventLoad"
          unload: "#/components/schemas/EventUnload"
    FilterFixed:
      type: object
      properties:
        eq:
          type: string
          description: Equal to.
        neq:
          type: string
          description: Not equal to.
        in:
          type: string
          description: In.
        not_in:
          type: string
          description: Not in.
    FilterString:
      type: object
      properties:
        eq:
          type: string
          description: Equal to.
        neq:
          type: string
          description: Not equal to.
        contains:
          type: string
          description: Contains.
        not_contains:
          type: string
          description: Does not contain.
        starts_with:
          type: string
          description: Starts with.
        not_starts_with:
          type: string
          description: Does not start with.
        ends_with:
          type: string
          description: Ends with.
        not_ends_with:
          type: string
          description: Does not end with.
        in:
          type: string
          description: In.
        not_in:
          type: string
          description: Not in.
    UserGet:
      type: object
      title: UserGet
      description: Response body for getting a user.
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 120
        language:
          type: string
          enum: [en]
          default: en
        dateCreated:
          type: integer
          format: int64
        dateUpdated:
          type: integer
          format: int64
      required:
        - username
        - language
        - dateCreated
        - dateUpdated
    UserPatch:
      type: object
      title: UserPatch
      description: Request body for updating a user.
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 120
        password:
          type: string
          minLength: 5
          maxLength: 128
          format: password
        language:
          type: string
          enum: [en]
          default: en
    WebsiteGet:
      type: object
      title: WebsiteGet
      description: Response body for getting a website.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        hostname:
          type: string
          minLength: 1
          maxLength: 253 # FQDN limit
          format: hostname
      required:
        - name
        - hostname
    WebsiteCreate:
      type: object
      title: WebsiteCreate
      description: Request body for creating a website.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        hostname:
          type: string
          minLength: 1
          maxLength: 253 # FQDN limit
          format: hostname
      required:
        - name
        - hostname
    WebsitePatch:
      type: object
      title: WebsitePatch
      description: Request body for updating a website.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        hostname:
          type: string
          minLength: 1
          maxLength: 253 # FQDN limit
          format: hostname
    StatsSummary:
      type: object
      title: StatsSummary
      properties:
        current:
          type: object
          properties:
            visitors:
              type: integer
            pageviews:
              type: integer
            bounces:
              type: integer
            duration:
              type: integer
          required:
            - visitors
            - pageviews
            - bounces
            - duration
        previous:
          type: object
          properties:
            visitors:
              type: integer
            pageviews:
              type: integer
            bounces:
              type: integer
            duration:
              type: integer
          required:
            - visitors
            - pageviews
            - bounces
            - duration
      required:
        - current
    StatsPages:
      type: array
      title: StatsPages
      items:
        type: object
        properties:
          path:
            type: string
            description: Pathname of the page.
          visitors:
            type: integer
            description: Number of unique visitors for given page.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors for given page.
            format: float
          pageviews:
            type: integer
            description: Number of page views.
          pageviews_percentage:
            type: number
            description: Percentage of page views.
            format: float
          bounces:
            type: integer
            description: Number of bounces.
          duration:
            type: integer
            description: Total time spent on page in milliseconds.
        required:
          - path
          - visitors
          - visitors_percentage
    StatsTime:
      type: array
      title: StatsTime
      items:
        type: object
        properties:
          path:
            type: string
            description: Pathname of the page.
          duration:
            type: integer
            description: Median time spent on page in milliseconds.
          duration_upper_quartile:
            type: integer
            description: Total time spent on page in milliseconds for the upper quartile (75%).
          duration_lower_quartile:
            type: integer
            description: Total time spent on page in milliseconds for the lower quartile (25%).
          duration_percentage:
            type: number
            description: Percentage of time contributing to the total time spent on the website.
            format: float
          visitors:
            type: integer
            description: Number of unique visitors for given page.
          bounces:
            type: integer
            description: Number of bounces.
        required:
          - path
          - duration
          - duration_percentage
    StatsReferrers:
      type: array
      title: StatsReferrers
      items:
        type: object
        properties:
          referrer:
            type: string
            description: Referrer URL.
          visitors:
            type: integer
            description: Number of unique visitors from referrer.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from referrer.
            format: float
          bounces:
            type: integer
            description: Number of bounces from referrer.
          duration:
            type: integer
            description: Total time spent on page from referrer in milliseconds.
        required:
          - referrer
          - visitors
          - visitors_percentage
    StatsUTMSources:
      type: array
      title: StatsUTMSources
      items:
        type: object
        properties:
          source:
            type: string
            description: UTM source.
          visitors:
            type: integer
            description: Number of unique visitors from UTM source.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from UTM source.
            format: float
        required:
          - source
          - visitors
          - visitors_percentage
    StatsUTMMediums:
      type: array
      title: StatsUTMMediums
      items:
        type: object
        properties:
          medium:
            type: string
            description: UTM medium.
          visitors:
            type: integer
            description: Number of unique visitors from UTM medium.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from UTM medium.
            format: float
        required:
          - medium
          - visitors
          - visitors_percentage
    StatsUTMCampaigns:
      type: array
      title: StatsUTMCampaigns
      items:
        type: object
        properties:
          campaign:
            type: string
            description: UTM campaign.
          visitors:
            type: integer
            description: Number of unique visitors from UTM campaign.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from UTM campaign.
            format: float
        required:
          - campaign
          - visitors
          - visitors_percentage
    StatsBrowsers:
      type: array
      title: StatsBrowsers
      items:
        type: object
        properties:
          browser:
            type: string
            description: Browser name.
          visitors:
            type: integer
            description: Number of unique visitors from browser.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from browser.
            format: float
        required:
          - browser
          - visitors
          - visitors_percentage
    StatsOS:
      type: array
      title: StatsOS
      items:
        type: object
        properties:
          os:
            type: string
            description: OS name.
          visitors:
            type: integer
            description: Number of unique visitors from OS.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from OS.
            format: float
        required:
          - os
          - visitors
          - visitors_percentage
    StatsDevices:
      type: array
      title: StatsDevices
      items:
        type: object
        properties:
          device:
            type: string
            description: Device name.
          visitors:
            type: integer
            description: Number of unique visitors from device.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from device.
            format: float
        required:
          - device
          - visitors
          - visitors_percentage
    StatsCountries:
      type: array
      title: StatsCountries
      items:
        type: object
        properties:
          country:
            type: string
            description: Country name.
          visitors:
            type: integer
            description: Number of unique visitors from country.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors from country.
            format: float
        required:
          - country
          - visitors
          - visitors_percentage
    StatsLanguages:
      type: array
      title: StatsLanguages
      items:
        type: object
        properties:
          language:
            type: string
            description: Language name.
          visitors:
            type: integer
            description: Number of unique visitors for language.
          visitors_percentage:
            type: number
            description: Percentage of unique visitors for language.
            format: float
        required:
          - language
          - visitors
          - visitors_percentage