openapi: 3.0.1
info:
  title: Rybbit Analytics API
  description: Rybbit is an open-source, privacy-friendly web and product analytics platform. This specification covers the public event ingestion endpoint (POST /api/track) used by the tracking script and server-side integrations, and the Bearer-key-authenticated Stats API (beta) for querying sites, sessions, users, retention, and events. The cloud base URL is https://app.rybbit.io; self-hosted instances expose the same paths on their own domain.
  termsOfService: https://www.rybbit.io/terms
  contact:
    name: Rybbit
    url: https://www.rybbit.io
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1.0'
servers:
- url: https://app.rybbit.io
  description: Rybbit Cloud
- url: https://your-instance.example.com
  description: Self-hosted instance (AGPL-3.0)
security:
- bearerAuth: []
tags:
- name: Analytics
  description: Stats API for events and reporting per site.
paths:
  /api/sites/{site}/users:
    get:
      operationId: listUsers
      tags:
      - Analytics
      summary: List users for a site.
      parameters:
      - $ref: '#/components/parameters/Site'
      - name: page
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: A list of users.
  /api/sites/{site}/users/{userId}:
    get:
      operationId: getUser
      tags:
      - Analytics
      summary: Get a single user.
      parameters:
      - $ref: '#/components/parameters/Site'
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User detail.
  /api/sites/{site}/users/{userId}/sessions:
    get:
      operationId: listUserSessions
      tags:
      - Analytics
      summary: List sessions for a user.
      parameters:
      - $ref: '#/components/parameters/Site'
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sessions for the user.
  /api/sites/{site}/users/session-count:
    get:
      operationId: getUserSessionCount
      tags:
      - Analytics
      summary: Get per-user session counts.
      parameters:
      - $ref: '#/components/parameters/Site'
      - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: Session counts grouped by user.
  /api/sites/{site}/journeys:
    get:
      operationId: getJourneys
      tags:
      - Analytics
      summary: Get user journeys.
      description: Returns common navigation paths (journeys) users take through the site.
      parameters:
      - $ref: '#/components/parameters/Site'
      - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: Journey data.
components:
  parameters:
    Filters:
      name: filters
      in: query
      required: false
      description: JSON-encoded array of filter objects to narrow results by browser, device, location, page data, UTM parameters, or user/event properties.
      schema:
        type: string
    Site:
      name: site
      in: path
      required: true
      description: The site ID (string or number) scoping the query.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'User-scoped API key with organization-level access. Keys begin with "rb_" and are 35 characters long. Send as `Authorization: Bearer rb_...`. A `?api_key=` query parameter is also accepted for quick testing only. API keys and rate limits apply to the Stats API on Rybbit Cloud; self-hosted instances have no rate limits.'