openapi: 3.0.3
info:
  title: Umami Analytics Authentication Website Statistics API
  description: The Umami Analytics API provides programmatic access to website analytics data including pageviews, sessions, events, and metrics. Umami is an open source, privacy-first web analytics platform that collects data without cookies or personal data storage. The API supports website management, session tracking, real-time visitor data, and analytics reporting for self-hosted and cloud instances. Self-hosted instances use JWT bearer tokens from the auth endpoint; Umami Cloud uses API key authentication.
  version: '1.0'
  contact:
    name: Umami Support
    url: https://umami.is/docs/support
  termsOfService: https://umami.is/terms
  x-generated-from: documentation
servers:
- url: https://api.umami.is
  description: Umami Cloud API
- url: http://localhost:3000
  description: Self-hosted Umami instance
security:
- bearerAuth: []
tags:
- name: Website Statistics
  description: Analytics metrics, pageviews, and statistics
paths:
  /api/websites/{websiteId}/stats:
    get:
      operationId: getWebsiteStats
      summary: Umami Website Stats
      description: Retrieve summarized statistics for a website within a given time range.
      tags:
      - Website Statistics
      parameters:
      - name: websiteId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Website identifier
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - name: startAt
        in: query
        required: true
        schema:
          type: integer
        description: Start timestamp in milliseconds
        example: 1704067200000
      - name: endAt
        in: query
        required: true
        schema:
          type: integer
        description: End timestamp in milliseconds
        example: 1704153600000
      responses:
        '200':
          description: Website statistics summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsiteStats'
              examples:
                getWebsiteStats200Example:
                  summary: Default getWebsiteStats 200 response
                  x-microcks-default: true
                  value:
                    pageviews:
                      value: 1500
                      change: 150
                    visitors:
                      value: 800
                      change: 80
                    visits:
                      value: 1000
                      change: 100
                    bounces:
                      value: 400
                      change: -20
                    totaltime:
                      value: 72000
                      change: 7200
        '401':
          description: Unauthorized
        '404':
          description: Website not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/websites/{websiteId}/pageviews:
    get:
      operationId: getWebsitePageviews
      summary: Umami Website Pageviews
      description: Retrieve pageview data bucketed by time unit within a given date range.
      tags:
      - Website Statistics
      parameters:
      - name: websiteId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Website identifier
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - name: startAt
        in: query
        required: true
        schema:
          type: integer
        description: Start timestamp in milliseconds
        example: 1704067200000
      - name: endAt
        in: query
        required: true
        schema:
          type: integer
        description: End timestamp in milliseconds
        example: 1704153600000
      - name: unit
        in: query
        required: true
        schema:
          type: string
          enum:
          - minute
          - hour
          - day
          - month
          - year
        description: Time bucket unit
        example: day
      - name: timezone
        in: query
        required: true
        schema:
          type: string
        description: IANA timezone name
        example: America/New_York
      responses:
        '200':
          description: Pageview time series data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageviewData'
              examples:
                getWebsitePageviews200Example:
                  summary: Default getWebsitePageviews 200 response
                  x-microcks-default: true
                  value:
                    pageviews:
                    - x: '2026-01-15 00:00:00'
                      y: 245
                    sessions:
                    - x: '2026-01-15 00:00:00'
                      y: 180
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/websites/{websiteId}/metrics:
    get:
      operationId: getWebsiteMetrics
      summary: Umami Website Metrics
      description: Retrieve metrics for a website broken down by a specific dimension.
      tags:
      - Website Statistics
      parameters:
      - name: websiteId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Website identifier
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - name: startAt
        in: query
        required: true
        schema:
          type: integer
        description: Start timestamp in milliseconds
        example: 1704067200000
      - name: endAt
        in: query
        required: true
        schema:
          type: integer
        description: End timestamp in milliseconds
        example: 1704153600000
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - url
          - title
          - referrer
          - browser
          - os
          - device
          - screen
          - country
          - language
          - event
        description: Metric dimension to retrieve
        example: url
      - name: limit
        in: query
        schema:
          type: integer
          default: 500
        description: Maximum number of results
        example: 20
      responses:
        '200':
          description: Metrics data by dimension
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Metric'
              examples:
                getWebsiteMetrics200Example:
                  summary: Default getWebsiteMetrics 200 response
                  x-microcks-default: true
                  value:
                  - x: /home
                    y: 450
                  - x: /blog
                    y: 220
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/websites/{websiteId}/active:
    get:
      operationId: getActiveVisitors
      summary: Umami Active Visitors
      description: Retrieve the number of currently active visitors on a website.
      tags:
      - Website Statistics
      parameters:
      - name: websiteId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Website identifier
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      responses:
        '200':
          description: Active visitor count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveVisitors'
              examples:
                getActiveVisitors200Example:
                  summary: Default getActiveVisitors 200 response
                  x-microcks-default: true
                  value:
                    visitors: 42
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Metric:
      type: object
      description: Analytics metric data point
      properties:
        x:
          type: string
          description: Dimension value (timestamp, URL, browser name, etc.)
          example: /home
        y:
          type: integer
          description: Metric value (count)
          example: 450
    ActiveVisitors:
      type: object
      description: Count of currently active visitors
      properties:
        visitors:
          type: integer
          description: Number of active visitors in the last 5 minutes
          example: 42
    WebsiteStats:
      type: object
      description: Summarized website analytics statistics
      properties:
        pageviews:
          type: object
          description: Pageview count and change
          properties:
            value:
              type: integer
              description: Total pageviews
              example: 1500
            change:
              type: integer
              description: Change from previous period
              example: 150
        visitors:
          type: object
          description: Unique visitor count and change
          properties:
            value:
              type: integer
              description: Unique visitors
              example: 800
            change:
              type: integer
              description: Change from previous period
              example: 80
        visits:
          type: object
          description: Visit count and change
          properties:
            value:
              type: integer
              description: Total visits
              example: 1000
            change:
              type: integer
              description: Change from previous period
              example: 100
        bounces:
          type: object
          description: Bounce count and change
          properties:
            value:
              type: integer
              description: Bounce count
              example: 400
            change:
              type: integer
              description: Change from previous period
              example: -20
        totaltime:
          type: object
          description: Total time on site in seconds and change
          properties:
            value:
              type: integer
              description: Total time in seconds
              example: 72000
            change:
              type: integer
              description: Change from previous period
              example: 7200
    PageviewData:
      type: object
      description: Time series pageview and session data
      properties:
        pageviews:
          type: array
          description: Pageview data points
          items:
            $ref: '#/components/schemas/Metric'
        sessions:
          type: array
          description: Session data points
          items:
            $ref: '#/components/schemas/Metric'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token obtained from POST /api/auth/login or Umami Cloud API key