Bearer-key-authenticated read API (beta) for querying analytics per site - events, users, journeys, and supporting stats - under the /api/sites/:site path. Supports date-range or relative time parameters and a JSON-encoded filters array.
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