openapi: 3.0.1
info:
  title: Rybbit 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: Event Tracking
    description: Public ingestion endpoint for pageviews and custom events.
  - name: Sites
    description: Site and organization management.
  - name: Analytics
    description: Stats API for events and reporting per site.
  - name: Sessions
    description: Session-level analytics and cohort retention.
paths:
  /api/track:
    post:
      operationId: trackEvent
      tags:
        - Event Tracking
      summary: Send a pageview or custom event.
      description: >-
        Public ingestion endpoint used by the Rybbit tracking script and
        server-side / mobile integrations. No API key is required for basic
        tracking; the server validates the payload, resolves the site by
        site_id, and applies rate limiting. The `type` field selects the
        event kind (pageview, custom_event, or outbound).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackRequest'
      responses:
        '200':
          description: Event accepted.
        '400':
          description: Bad Request - payload failed validation.
        '429':
          description: Too Many Requests - rate limit exceeded.
  /api/sites/{site}/sessions:
    get:
      operationId: listSessions
      tags:
        - Sessions
      summary: List sessions for a site.
      description: Returns a paginated list of sessions with their analytics data.
      parameters:
        - $ref: '#/components/parameters/Site'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: start_date
          in: query
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          schema:
            type: string
            format: date
        - name: time_zone
          in: query
          schema:
            type: string
        - name: user_id
          in: query
          schema:
            type: string
        - name: identified_only
          in: query
          schema:
            type: boolean
        - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: A paginated list of sessions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
        '401':
          description: Unauthorized - missing or invalid API key.
        '403':
          description: Forbidden - no access to site.
  /api/sites/{site}/sessions/{sessionId}:
    get:
      operationId: getSession
      tags:
        - Sessions
      summary: Get a single session.
      description: Returns session-level detail including the ordered list of pageviews and events.
      parameters:
        - $ref: '#/components/parameters/Site'
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: Not Found.
  /api/sites/{site}/session-locations:
    get:
      operationId: listSessionLocations
      tags:
        - Sessions
      summary: List session locations.
      description: Returns geographic location data for sessions, suitable for map visualizations.
      parameters:
        - $ref: '#/components/parameters/Site'
        - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: Session location data.
  /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}/retention:
    get:
      operationId: getRetention
      tags:
        - Sessions
      summary: Get cohort retention.
      description: >-
        Returns cohort-based retention analysis. Users are grouped into
        cohorts by first visit and retention is tracked over subsequent time
        periods.
      parameters:
        - $ref: '#/components/parameters/Site'
        - name: start_date
          in: query
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: Cohort retention data.
  /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:
  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.
  parameters:
    Site:
      name: site
      in: path
      required: true
      description: The site ID (string or number) scoping the query.
      schema:
        type: string
    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
  schemas:
    TrackRequest:
      type: object
      required:
        - site_id
        - type
      properties:
        site_id:
          type: string
          description: The Rybbit site identifier the event belongs to.
        type:
          type: string
          enum:
            - pageview
            - custom_event
            - outbound
          description: The kind of event being recorded.
        event_name:
          type: string
          description: Name of the custom event (required for custom_event).
        hostname:
          type: string
        pathname:
          type: string
        querystring:
          type: string
        page_title:
          type: string
        referrer:
          type: string
        language:
          type: string
        screenWidth:
          type: integer
        screenHeight:
          type: integer
        user_agent:
          type: string
        properties:
          type: string
          description: JSON-encoded string of custom event properties.
    Session:
      type: object
      properties:
        session_id:
          type: string
        user_id:
          type: string
        identified_user_id:
          type: string
        traits:
          type: object
          additionalProperties: true
        country:
          type: string
        region:
          type: string
        city:
          type: string
        browser:
          type: string
        operating_system:
          type: string
        device_type:
          type: string
        referrer:
          type: string
        channel:
          type: string
        entry_page:
          type: string
        exit_page:
          type: string
        pageviews:
          type: integer
        events:
          type: integer
        session_duration:
          type: number
        session_start:
          type: string
          format: date-time
        session_end:
          type: string
          format: date-time
        utm_source:
          type: string
        utm_medium:
          type: string
        utm_campaign:
          type: string