πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Fix 90+ documentation inconsistencies found by docs-vs-code audit (#1054)
Goldflagf7bede23c1a3
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.ymlindex 5b2661152..c174bca8d 100644--- a/.github/workflows/docker-publish.yml+++ b/.github/workflows/docker-publish.yml@@ -9,6 +9,9 @@ on:pull_request:branches:- master+ paths-ignore:+ - "docs/**"+ - "**.md"jobs:build-client:diff --git a/client/src/app/[site]/api-playground/utils/endpointConfig.ts b/client/src/app/[site]/api-playground/utils/endpointConfig.tsindex b3f3a990d..1fed8241d 100644--- a/client/src/app/[site]/api-playground/utils/endpointConfig.ts+++ b/client/src/app/[site]/api-playground/utils/endpointConfig.ts@@ -134,7 +134,7 @@ export const endpointCategories: EndpointCategory[] = [path: "/organizations",name: "Get My Organizations",description:- "Returns all organizations the authenticated user is a member of, including all members for each organization",+ "Returns all organizations the authenticated user is a member of. The members array is only populated for session-cookie requests; Bearer/API-key callers receive an empty members array and should use Get Organization Members instead.",hasCommonParams: false,},{@@ -333,6 +333,38 @@ export const endpointCategories: EndpointCategory[] = [specificParams: ["event_name"],requiredParams: ["event_name"],},+ {+ method: "GET",+ path: "/sites/:site/events/autocapture",+ name: "Get Autocapture Events",+ description: "Returns autocapture events of a given type grouped by display value with counts",+ hasCommonParams: true,+ requiredParams: ["type"],+ specificParams: ["type"],+ parameterMetadata: {+ type: {+ label: "Type",+ type: "select",+ options: ["outbound", "button_click", "form_submit", "copy"],+ },+ },+ },+ {+ method: "GET",+ path: "/sites/:site/events/autocapture-values",+ name: "Get Autocapture Values",+ description: "Returns the most common prop values for an autocapture type (goal/funnel suggestions)",+ hasCommonParams: true,+ requiredParams: ["type"],+ specificParams: ["type"],+ parameterMetadata: {+ type: {+ label: "Type",+ type: "select",+ options: ["outbound", "button_click", "form_submit", "copy"],+ },+ },+ },{method: "GET",path: "/sites/:site/events/outbound",@@ -649,7 +681,16 @@ export const endpointCategories: EndpointCategory[] = [name: "Get Sessions",description: "Returns a paginated list of sessions",hasCommonParams: true,- specificParams: ["page", "limit", "user_id", "identified_only", "min_pageviews", "min_events", "min_duration"],+ specificParams: [+ "page",+ "limit",+ "user_id",+ "session_id",+ "identified_only",+ "min_pageviews",+ "min_events",+ "min_duration",+ ],},{method: "GET",@@ -900,6 +941,7 @@ export const parameterMetadata: Record<string, ParameterMetadata> = {errorMessage: { label: "Error Message", type: "text", placeholder: "Error message to filter by" },user_id: { label: "User ID", type: "text", placeholder: "User ID" },userId: { label: "User ID", type: "text", placeholder: "User ID" },+ session_id: { label: "Session ID", type: "text", placeholder: "Session ID" },key: { label: "Key", type: "text", placeholder: "Trait key" },value: { label: "Value", type: "text", placeholder: "Trait value" },search: { label: "Search", type: "text", placeholder: "Search users" },diff --git a/docs/content/docs/(docs)/account-settings.mdx b/docs/content/docs/(docs)/account-settings.mdxindex d8f80767f..9bb3761bf 100644--- a/docs/content/docs/(docs)/account-settings.mdx+++ b/docs/content/docs/(docs)/account-settings.mdx@@ -48,8 +48,13 @@ Generate API keys to access Rybbit's analytics endpoints from your applications.### Creating an API Key1. Enter a name for your API key (e.g., "Production App", "Development")-2. Click "Create"-3. Copy and save the generated key immediately+2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.+3. Click "Create"+4. Copy and save the generated key immediately++<Callout type="warn">+ On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.+</Callout><Callout type="warn">API keys are only shown once when created. Store your key securely as you won't be able to view it again.@@ -60,7 +65,9 @@ Generate API keys to access Rybbit's analytics endpoints from your applications.Your existing API keys are displayed in a table showing:- **Name** - The name you assigned to the key- **Key** - A preview of the key (first few characters)+- **Permissions** - Whether the key has full access or is restricted to specific scopes- **Created** - When the key was created+- **Last used** - When the key last made a requestYou can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.diff --git a/docs/content/docs/(docs)/architecture.mdx b/docs/content/docs/(docs)/architecture.mdxdeleted file mode 100644index b3a3bf93d..000000000--- a/docs/content/docs/(docs)/architecture.mdx+++ /dev/null@@ -1,244 +0,0 @@-----title: Architecture-description: Understanding Rybbit's architecture------## Overview--Rybbit is a modern, open-source web and product analytics platform designed as a privacy-friendly alternative to Google Analytics. Built with a full-stack TypeScript architecture, it provides real-time analytics, session replay, performance monitoring, and uptime tracking capabilities.--## System Architecture--<Tabs items={['Cloud', 'Self-Hosted']} defaultIndex={0}>-<Tab value="Self-Hosted">-<Mermaid- chart="-graph TB- subgraph Client Applications- A[Tracked Website]- B[Dashboard UI<br/>Next.js 15]- end-- subgraph Rybbit Server- C[Caddy<br/>HTTP/3 Support]- subgraph Backend Service- D[Fastify Server<br/>Node.js]- E[Better Auth<br/>Authentication]- K[MaxMind GeoIP<br/>IP Geolocation]- end-- G[(PostgreSQL<br/>Metadata & Users)]- H[(ClickHouse<br/>Events & Analytics)]- end-- A -->|Track Events| C- B -->|API Requests| C- C -->|Route Traffic| D-- D -->|Auth| E- E -->|Sessions| G- D -->|User Data| G- D -->|Analytics Data| H- D -->|IP Lookup| K-"-/>-</Tab>--<Tab value="Cloud">-<Mermaid- chart="-graph TB- subgraph Client Applications- A[Tracked Website]- B[Dashboard UI<br/>Next.js 15]- end-- subgraph Rybbit Server- C[Caddy<br/>HTTP/3 Support]- subgraph Backend Service- D[Fastify Server<br/>Node.js]- E[Better Auth<br/>Authentication]- K[MaxMind GeoIP<br/>IP Geolocation]- end-- G[(PostgreSQL<br/>Metadata & Users)]- H[(ClickHouse<br/>Events & Analytics)]- end-- subgraph External Services- I[Cloudflare R2<br/>Session Replays]- J[Resend<br/>Email Service]- end-- A -->|Track Events| C- B -->|API Requests| C- C -->|Route Traffic| D-- D -->|Auth| E- E -->|Sessions| G- D -->|Queue Jobs| F- D -->|User Data| G- D -->|Analytics Data| H- D -->|Store Replays| I- D -->|Send Emails| J- D -->|IP Lookup| K-- F -->|Process Events| H-"-/>-</Tab>-</Tabs>--## Core Components--### Frontend (Client)--**Technology Stack:**-- **Framework**: Next.js 15 with App Router and Turbopack-- **UI Library**: React 19 with Shadcn UI components-- **Styling**: Tailwind CSS-- **State Management**:- - Zustand for global state- - Tanstack Query for server state- - Jotai for atomic state-- **Data Visualization**:- - Nivo charts (bar, line, calendar)- - React Globe GL for 3D visualizations- - Leaflet for maps-- **Forms**: React Hook Form with Zod validation-- **Authentication**: Better Auth client--### Backend (Server)--**Technology Stack:**-- **Framework**: Fastify with TypeScript-- **ORM**: Drizzle ORM-- **Authentication**: Better Auth with session management-- **Validation**: Zod schemas-- **Rate Limiting**: Fastify rate limit plugin--### Database Layer--#### PostgreSQL-**Purpose**: Relational data and application state--**Schema Management**: Drizzle ORM with migrations--#### ClickHouse-**Purpose**: High-performance analytics data storage--### Tracking Script--**Location**: `server/src/analytics-script/`--**Build**:-- Bundled with esbuild-- Minified with Terser-- Served as static file--**Features:**-- Automatic pageview tracking-- SPA route change detection-- Custom event API-- Session replay (optional)-- Web Vitals collection (optional)-- Error tracking (optional)-- Outbound link tracking--**Size**: ~18KB uncompressed--### Infrastructure--#### Docker Compose Architecture--**Services:**--1. **Caddy** (Reverse Proxy)- - Automatic HTTPS with Let's Encrypt- - HTTP/3 support- - Routes traffic to client and backend--2. **Client** (Frontend)- - Next.js production build- - Static asset serving--3. **Backend** (API Server)- - Fastify server- - Environment-based configuration--4. **ClickHouse**- - Custom network configuration- - JSON type support- - Minimal logging for performance- - Persistent volume for data--5. **PostgreSQL**- - User and site data- - Health checks- - Persistent volume--**Cloud Additions:**-- R2 integration for session replay storage-- Stripe webhook handling--## Data Flow--### Event Tracking Flow--```-1. User action on tracked website-2. Tracking script captures event-3. POST to /api/track endpoint-4. Server validates payload (Zod)-5. API key validation (if provided)-6. Rate limiting check-7. Site configuration lookup-8. Bot detection (if enabled)-9. Monthly limit check-10. IP exclusion check-11. User agent parsing-12. Geolocation lookup (MaxMind)-13. Session update (PostgreSQL)-14. Event written to ClickHouse-15. Real-time updates broadcasted-```--### Query Flow--```-1. Dashboard makes API request-2. Authentication check (Better Auth)-3. Site ownership validation-4. Query parameters parsed-5. Filter conditions built-6. ClickHouse query executed-7. Results aggregated-8. Response formatted and cached-9. UI updated with data-```--## Deployment Models--### Self-Hosted-- Most feature access-- All data stored in ClickHouse-- No external dependencies required-- Docker Compose deployment--### Cloud (rybbit.io)-- Managed hosting on Hetzner (EU)-- Stripe integration for billing-- Cloudflare R2 storage for session replays-- Multi-region uptime monitoring-- Usage tracking with materialized views--## Security & Privacy--- **No cookies**: User identification via IP+UA hash-- **Daily rotating salt**: Optional for enhanced privacy-- **IP exclusion**: Filter internal traffic-- **Bot blocking**: isbot integration-- **Rate limiting**: API key and IP-based-- **No cookies**: Privacy-first design-- **Session-based auth**: Better Auth with secure tokens-- **Minimal data retention**: Configurable TTL policies\ No newline at end of filediff --git a/docs/content/docs/(docs)/data-import.mdx b/docs/content/docs/(docs)/data-import.mdxindex a6655a8c6..f45ccd3cd 100644--- a/docs/content/docs/(docs)/data-import.mdx+++ b/docs/content/docs/(docs)/data-import.mdx@@ -14,9 +14,14 @@ Currently, Rybbit supports importing data from:- Umami- Simple Analytics+- PlausibleAdditional platforms may be added in the future based on user demand.+<Callout type="info">+ Umami and Simple Analytics are imported from a CSV export, while Plausible is imported from its ZIP export. The Import dialog automatically expects the correct file type for the platform you select.+</Callout>+## Plan Requirements### Cloud Version@@ -26,7 +31,6 @@ Additional platforms may be added in the future based on user demand.| Free | β Not available | - | - || Standard | β Available | 36 months (3 years) | Plan limit applies || Pro | β Available | 60 months (5 years) | Plan limit applies |-| AppSumo | β Available | 24 months | Plan limit applies |### Self-Hosted Version@@ -42,7 +46,6 @@ Self-hosted installations have **unlimited** access to data imports with no restThe historical data window determines how far back you can import data:- **Standard plans**: Import data from the past 36 months (3 years)-- **AppSumo plans**: Import data from the past 24 months- **Pro plans**: Import data from the past 60 months (5 years)- **Self-hosted**: Unlimited - import data from any date@@ -82,6 +85,11 @@ Self-hosted users have no concurrent import restrictions.2. Navigate to Export section3. Download your analytics data as CSV+**Plausible:**+1. Open your site's dashboard+2. Use the CSV export option to download your data+3. Keep the exported **ZIP** archive as-is β do not unzip it+</Step><Step>@@ -96,10 +104,10 @@ Self-hosted users have no concurrent import restrictions.<Step>-### Select Platform and Upload CSV+### Select Platform and Upload File1. Select your source platform from the dropdown-2. Click "Choose File" and select your exported CSV+2. Click "Choose File" and select your exported file (a **CSV** for Umami and Simple Analytics, or a **ZIP** for Plausible)3. Click the **Import** button<Callout type="warn">@@ -182,7 +190,7 @@ Each import shows three key metrics:**Cause:** Events are older than your plan's historical data window.**Solution:**-- Upgrade to Pro plan for 60-month history (vs 36-month on Standard)+- Upgrade to Pro plan for 60-month history (vs 24-month on Standard)- For self-hosted, no action needed - all dates are allowed- Filter your CSV export to only include recent datadiff --git a/docs/content/docs/(docs)/embeds/widget.mdx b/docs/content/docs/(docs)/embeds/widget.mdxindex 53dcb20bd..a9035c986 100644--- a/docs/content/docs/(docs)/embeds/widget.mdx+++ b/docs/content/docs/(docs)/embeds/widget.mdx@@ -45,7 +45,7 @@ A self-contained dashboard card showing the live count, an optional bar chart of### Inline Pill-A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit wordmark.+A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit logo.## Appearancediff --git a/docs/content/docs/(docs)/experiments.mdx b/docs/content/docs/(docs)/experiments.mdxindex 8cd11dfb6..beec7ab36 100644--- a/docs/content/docs/(docs)/experiments.mdx+++ b/docs/content/docs/(docs)/experiments.mdx@@ -20,7 +20,7 @@ An experiment has three moving parts:| Part | What it does || --- | --- || **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages. |-| **Exposure** | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. Exposures are the denominator for each variant's conversion rate. |+| **Exposure** | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. || **Conversion** | The experiment's primary goal β a page visit or a custom event β counts as a conversion for whichever variant the visitor was assigned. |Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.@@ -128,7 +128,7 @@ Each experiment shows a results panel comparing every variant. Results respect t| --- | --- || **Variant** | The variant key, with the **Control** marked as the baseline. || **Sessions** | Sessions exposed to that variant, alongside the number that converted. |-| **Conversion rate** | Conversions divided by exposures for that variant. |+| **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant. || **Lift** | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red. || **Confidence** | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |diff --git a/docs/content/docs/(docs)/feature-guides/errors.mdx b/docs/content/docs/(docs)/feature-guides/errors.mdxindex d7f0970ee..c501d4877 100644--- a/docs/content/docs/(docs)/feature-guides/errors.mdx+++ b/docs/content/docs/(docs)/feature-guides/errors.mdx@@ -16,10 +16,9 @@ For each error, you'll see:- **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.- **Error Message** - The specific error message- **Stack Trace** - The chain of function calls that led to the error-- **Affected Users** - Number of unique users who encountered this error+- **Affected Sessions** - Number of unique sessions in which this error occurred- **Occurrence Count** - How many times the error was triggered-- **First/Last Seen** - When the error first appeared and most recently occurred-- **Affected Pages** - Which pages generated this error+Expanding an error shows its individual occurrences, including the timestamp and page for each event.- **Browser & Device** - Which environments experience this error## Using Error Datadiff --git a/docs/content/docs/(docs)/feature-guides/events.mdx b/docs/content/docs/(docs)/feature-guides/events.mdxindex c5a735a56..4d3c89215 100644--- a/docs/content/docs/(docs)/feature-guides/events.mdx+++ b/docs/content/docs/(docs)/feature-guides/events.mdx@@ -13,19 +13,20 @@ See the [Track Events guide](/docs/track-events) for implementation details.The events page includes:- **Events Chart** - Visualize event trends over time-- **Custom Events List** - All tracked events with counts-- **Event Log** - Recent individual event occurrences+- **Event Log** - Recent individual event occurrences (click any row to open a details sheet)++The **Custom Events List** β all tracked events with counts β lives in the Events section of the main dashboard.## Event Metrics-For each event:+For each event in the Custom Events List:- **Event Name** - The name you assigned to the event- **Count** - Total times triggered in the selected period- **Percentage** - Share of total events## Event Properties-Click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).+In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).## Filteringdiff --git a/docs/content/docs/(docs)/feature-guides/journeys.mdx b/docs/content/docs/(docs)/feature-guides/journeys.mdxindex 4ac494bba..650279e44 100644--- a/docs/content/docs/(docs)/feature-guides/journeys.mdx+++ b/docs/content/docs/(docs)/feature-guides/journeys.mdx@@ -10,7 +10,7 @@ User journeys show the actual paths people take as they move through your websit## Reading the Visualization### Nodes-Each circle represents a page or event. The size indicates how many users reached that point.+Each bar represents a page or event. Its height indicates how many users reached that point.### ConnectionsLines between nodes show user flow. Thicker connections mean more users took that path.diff --git a/docs/content/docs/(docs)/feature-guides/main-tab.mdx b/docs/content/docs/(docs)/feature-guides/main-tab.mdxindex 6fd4e1aa0..886553b94 100644--- a/docs/content/docs/(docs)/feature-guides/main-tab.mdx+++ b/docs/content/docs/(docs)/feature-guides/main-tab.mdx@@ -18,7 +18,7 @@ The main dashboard is your home base in Rybbit Analytics, showing all key metric## Time Controls-Select date ranges: Today, Yesterday, Last 7/30/90 days, or custom range.+Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.## Filtersdiff --git a/docs/content/docs/(docs)/feature-guides/pages-tab.mdx b/docs/content/docs/(docs)/feature-guides/pages-tab.mdxindex ec6e4d5a6..a664b45d3 100644--- a/docs/content/docs/(docs)/feature-guides/pages-tab.mdx+++ b/docs/content/docs/(docs)/feature-guides/pages-tab.mdx@@ -23,6 +23,6 @@ Use the same filters as the main dashboard to analyze specific segments:## Identifying Issues-- Sort by lowest time on page to find content that isn't engaging-- Sort by fewest sessions to find underperforming pages+- Scan for pages with low time on page to find content that isn't engaging+- Look for pages with few sessions to find underperforming pages- Compare entry pages to see which content attracts trafficdiff --git a/docs/content/docs/(docs)/feature-guides/performance.mdx b/docs/content/docs/(docs)/feature-guides/performance.mdxindex c0398126f..cd7b47d64 100644--- a/docs/content/docs/(docs)/feature-guides/performance.mdx+++ b/docs/content/docs/(docs)/feature-guides/performance.mdx@@ -45,7 +45,7 @@ How long until the server responds.## Percentile Selector-Choose which percentile to view (p50, p75, p90, p95, p99). The p75 is commonly used for Core Web Vitals assessment.+Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.## Comparisondiff --git a/docs/content/docs/(docs)/feature-guides/session-replay.mdx b/docs/content/docs/(docs)/feature-guides/session-replay.mdxindex ceb2b0bec..1db76c885 100644--- a/docs/content/docs/(docs)/feature-guides/session-replay.mdx+++ b/docs/content/docs/(docs)/feature-guides/session-replay.mdx@@ -9,16 +9,7 @@ Session replay lets you watch anonymized recordings of real user sessions, showi## Enabling Session Replay-Enable session replay in your [site settings](/docs/site-settings), or add the attribute to your tracking script:--```html-<script- src="https://your-rybbit-instance.com/api/script.js"- data-site-id="YOUR_SITE_ID"- data-session-replay="true"- defer-></script>-```+Enable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically β no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)## What You'll Seediff --git a/docs/content/docs/(docs)/feature-guides/users.mdx b/docs/content/docs/(docs)/feature-guides/users.mdxindex c4969be2c..25eadd153 100644--- a/docs/content/docs/(docs)/feature-guides/users.mdx+++ b/docs/content/docs/(docs)/feature-guides/users.mdx@@ -19,12 +19,14 @@ For each user, you'll see:## Filtering Users-Filter by:+Filter by the standard dimension filters:-- Number of sessions or page views-- Specific events triggered-- Device type or location-- First visit or last activity date+- Device type, browser, or operating system+- Country, region, or city+- Referrer, channel, or UTM parameters+- Pages visited (pathname, entry, or exit page)++Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.## Identified Usersdiff --git a/docs/content/docs/(docs)/filter-traffic.mdx b/docs/content/docs/(docs)/filter-traffic.mdxindex 7dd9f5f0b..4d47f54e9 100644--- a/docs/content/docs/(docs)/filter-traffic.mdx+++ b/docs/content/docs/(docs)/filter-traffic.mdx@@ -134,7 +134,7 @@ If any filter matches, the event is accepted with a `200` response but is not trTo test country filtering locally, send a public IP through the `X-Real-IP` header:```bash-curl -X POST http://localhost:3000/track \+curl -X POST http://localhost:3001/api/track \-H "Content-Type: application/json" \-H "X-Real-IP: 8.8.8.8" \-d '{diff --git a/docs/content/docs/(docs)/guides/carrd.mdx b/docs/content/docs/(docs)/guides/carrd.mdxindex fac7bdc15..50eddd385 100644--- a/docs/content/docs/(docs)/guides/carrd.mdx+++ b/docs/content/docs/(docs)/guides/carrd.mdx@@ -9,7 +9,7 @@ import { Callout } from 'fumadocs-ui/components/callout';Carrd is a popular platform for building simple, responsive one-page sites. You can add Rybbit Analytics to track visitors on your Carrd site.<Callout type="warn">-Adding custom code requires a **Carrd Pro** subscription (Pro Standard, Pro Plus, or Pro Max).+Adding custom code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The custom-code Embeds feature is not included on Pro Lite.</Callout>## How to Add Rybbit to Carrd@@ -57,7 +57,7 @@ We use the JavaScript approach instead of a plain script tag because some site b## Using Multiple Pages-If your Carrd site has multiple pages (Pro Plus or Pro Max feature), the tracking script in the head code will automatically load on all pages.+If your Carrd site has multiple pages (Pro Plus feature), the tracking script in the head code will automatically load on all pages.## Troubleshootingdiff --git a/docs/content/docs/(docs)/guides/gitbook.mdx b/docs/content/docs/(docs)/guides/gitbook.mdxindex f2037e416..f2d6457b2 100644--- a/docs/content/docs/(docs)/guides/gitbook.mdx+++ b/docs/content/docs/(docs)/guides/gitbook.mdx@@ -1,33 +1,21 @@---title: GitBook-description: Integrate Rybbit Analytics with your GitBook documentation+description: Options for using Rybbit Analytics with GitBook documentation----import { Steps, Step } from 'fumadocs-ui/components/steps';import { Callout } from 'fumadocs-ui/components/callout';-GitBook is a popular platform for creating documentation and knowledge bases. You can add Rybbit Analytics to track how visitors use your documentation.+GitBook is a popular platform for creating documentation and knowledge bases.<Callout type="warn">-Custom scripts require a **Pro plan or higher** and a **custom domain** configured for your GitBook space.+GitBook no longer supports adding arbitrary custom scripts (JS/HTML) to published sites. The old **Custom scripts β Head** setting this guide previously described has been removed, so the standard Rybbit `<script>` snippet cannot be pasted into a GitBook-hosted site. Analytics on GitBook now works through its built-in integrations, and Rybbit does not currently have a prebuilt GitBook integration.</Callout>-## How to Add Rybbit to GitBook+## Current options-<Steps>-<Step>-### Open Space Settings+### Build a custom GitBook integration-1. Navigate to your GitBook space-2. Click on the **Settings** icon (gear) in the top right-3. Go to **Integrations** in the sidebar-</Step>--<Step>-### Add Custom Script--1. Scroll to the **Custom scripts** section-2. In the **Head** section, add the following code:+GitBook's [developer platform](https://gitbook.com/docs/integrations) lets you build and install your own integration, and integrations can inject scripts into published content β this is how GitBook's own analytics integrations (Google Analytics, Fathom, etc.) work. A minimal custom integration that injects the Rybbit snippet:```html<script@@ -37,38 +25,16 @@ Custom scripts require a **Pro plan or higher** and a **custom domain** configur></script>```-Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>--<Step>-### Save Changes--Click **Save** to apply the script to your documentation site.-</Step>-</Steps>--## Requirements--For custom scripts to work on GitBook, you need:--1. **Pro, Team, or Enterprise plan** - Custom scripts are not available on the free plan-2. **Custom domain** - Scripts only load on custom domains, not on `*.gitbook.io` URLs--## Troubleshooting--### Script not appearing+Refer to GitBook's integration documentation for the current manifest format and publishing flow, and note that script injection only applies to published spaces (typically on a custom domain).-1. Ensure you have a Pro plan or higher-2. Verify your custom domain is properly configured-3. Check that you're viewing the site through your custom domain, not `*.gitbook.io`+### Host your docs on a platform with custom-code support-### Changes not reflecting+If building an integration isn't worth it for your use case, platforms like [Docusaurus](/docs/guides/docusaurus), [VitePress](/docs/guides/vitepress), [Mintlify](/docs/guides/mintlify), or [Hugo](/docs/guides/hugo) support adding the Rybbit script directly β see their guides.-GitBook may cache pages. Try:-- Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)-- Viewing in an incognito/private window-- Waiting a few minutes for cache to update+## Verifying installation-### Tracking internal vs public docs+If you do get the script injected via an integration:-The tracking script will work for both public documentation and internal/private spaces (when accessed by authenticated users through your custom domain).+1. Visit your published documentation through its public URL+2. Open the browser Network tab and confirm `script.js` loads and `POST` requests go to `/api/track`+3. Check your Rybbit dashboard for incoming pageviewsdiff --git a/docs/content/docs/(docs)/guides/hugo.mdx b/docs/content/docs/(docs)/guides/hugo.mdxindex 50c029027..ec1118a64 100644--- a/docs/content/docs/(docs)/guides/hugo.mdx+++ b/docs/content/docs/(docs)/guides/hugo.mdx@@ -31,13 +31,13 @@ Paste your Rybbit tracking script into this new file:```html{{/* layouts/partials/rybbit-analytics.html */}}-{{ if not .Site.IsServer }} {{/* Only include in production builds */}}+{{ if not hugo.IsServer }} {{/* Only include in production builds */}}<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>{{ end }}```**Explanation:**-- `{{ if not .Site.IsServer }}`: This Hugo condition ensures that the tracking script is only included when you build your site for production (`hugo`) and not during local development (`hugo server`). This prevents tracking your own local page views.+- `{{ if not hugo.IsServer }}`: This Hugo condition ensures that the tracking script is only included when you build your site for production (`hugo`) and not during local development (`hugo server`). This prevents tracking your own local page views.- Replace `https://app.rybbit.io` and `YOUR_SITE_ID` with your actual details.</Step>@@ -73,7 +73,7 @@ Modify `layouts/partials/rybbit-analytics.html` to use a site parameter:```html{{/* layouts/partials/rybbit-analytics.html */}}-{{ if and (not .Site.IsServer) .Site.Params.rybbitSiteID }}+{{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}<script defer src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js" data-site-id="{{ .Site.Params.rybbitSiteID }}"></script>{{ end }}```diff --git a/docs/content/docs/(docs)/guides/laravel.mdx b/docs/content/docs/(docs)/guides/laravel.mdxindex e9f717044..876594f93 100644--- a/docs/content/docs/(docs)/guides/laravel.mdx+++ b/docs/content/docs/(docs)/guides/laravel.mdx@@ -11,7 +11,7 @@ Integrating Rybbit Analytics with your Laravel application is straightforward. Y<Step>### Get Your Tracking Script-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:+First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:```html<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>diff --git a/docs/content/docs/(docs)/guides/mintlify.mdx b/docs/content/docs/(docs)/guides/mintlify.mdxindex c81f95d43..34aca8297 100644--- a/docs/content/docs/(docs)/guides/mintlify.mdx+++ b/docs/content/docs/(docs)/guides/mintlify.mdx@@ -51,7 +51,7 @@ After deploying your Mintlify documentation site, open your Rybbit dashboard toLook for:- The `script.js` file being loaded in the Network tab-- POST requests to your Rybbit analytics endpoint (e.g., `/api/event`)+- POST requests to your Rybbit analytics endpoint (e.g., `/api/track`)</Step></Steps>diff --git a/docs/content/docs/(docs)/guides/prestashop.mdx b/docs/content/docs/(docs)/guides/prestashop.mdxindex 281ce8338..82c4f894d 100644--- a/docs/content/docs/(docs)/guides/prestashop.mdx+++ b/docs/content/docs/(docs)/guides/prestashop.mdx@@ -11,31 +11,36 @@ PrestaShop is a popular open-source e-commerce platform. Here's how to add Rybbi## How to Add Rybbit to PrestaShop-<Tabs items={['Back Office Settings', 'Theme Files']}>+<Tabs items={['Custom Code Module', 'Theme Files']}><Tab>-### Using Back Office Settings+### Using a Custom Code Module-PrestaShop allows adding custom code through the back office.+PrestaShop's back office has no native option for injecting custom code into the+`<head>`. To add the tracking script without editing template files, install a+custom-code / header-injection module.<Steps><Step>-### Access Theme Settings+### Install a Custom Code Module1. Log in to your PrestaShop Back Office-2. Go to **Design** > **Theme & Logo**-3. Scroll down to **Advanced customization** or click on **Pages Configuration**+2. Go to **Modules** > **Module Catalog** (or **Module Manager**)+3. Install a module that injects custom code into the page header β for example+ a "Custom HTML" or "Header/Head code" module from the+ [PrestaShop Addons marketplace](https://addons.prestashop.com/)++<Callout type="info">+PrestaShop does not ship a built-in head-injection UI, so a third-party module is+required for this method. If you prefer not to install one, use the **Theme Files**+tab instead.+</Callout></Step><Step>-### Add Custom Code+### Add the Tracking Script-Depending on your PrestaShop version:--**PrestaShop 1.7+:**-1. Go to **Design** > **Theme & Logo** > **Advanced customization**-2. Click on **Add a new HTML element**-3. Select position: `head` or `displayHeader`-4. Add the following code:+Open the module's configuration and paste the following into its head / header+code field:```html<script>@@ -49,18 +54,14 @@ Depending on your PrestaShop version:</script>```-**PrestaShop 8.x:**-1. Go to **Design** > **Theme & Logo** > **Pages Configuration**-2. Select **displayHead** hook-3. Add a custom HTML module with the script above-Replace `YOUR_SITE_ID` with your actual Site ID.</Step><Step>### Save Changes-Click **Save** to apply the tracking code to your store.+Save the module configuration and clear the cache under **Advanced Parameters** >+**Performance** to apply the tracking code to your store.</Step></Steps></Tab>diff --git a/docs/content/docs/(docs)/guides/react/next-js.mdx b/docs/content/docs/(docs)/guides/react/next-js.mdxindex 9d86c8b1f..6a2ce0259 100644--- a/docs/content/docs/(docs)/guides/react/next-js.mdx+++ b/docs/content/docs/(docs)/guides/react/next-js.mdx@@ -108,11 +108,29 @@ module.exports = {source: "/api/track",destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/track`,},+ {+ source: "/api/identify",+ destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/identify`,+ },+ {+ source: "/api/replay.js",+ destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/replay.js`,+ },+ {+ source: "/api/site/:path*",+ destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/site/:path*`,+ },+ {+ source: "/api/session-replay/:path*",+ destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/session-replay/:path*`,+ },]},}```+The script derives its API base from its own `src`, so once you serve it from `/api/script.js` it will call every other endpoint under `/api` on your own domain too. All six rewrites are required: `script.js` and `track` cover the script and pageview/event traffic, `identify` covers `identify()`, `replay.js` and `session-replay/:path*` cover session replay, and `site/:path*` covers the tracking-config and feature-flag requests. If you omit the `site/:path*` rewrite, the tracking-config fetch fails and the script silently falls back to its defaults, disabling web vitals, error tracking, session replay, and button/copy/form autocapture.+and where you are using the script:```jsxdiff --git a/docs/content/docs/(docs)/guides/shopify.mdx b/docs/content/docs/(docs)/guides/shopify.mdxindex 89befcf26..69d9ab98d 100644--- a/docs/content/docs/(docs)/guides/shopify.mdx+++ b/docs/content/docs/(docs)/guides/shopify.mdx@@ -169,49 +169,79 @@ document.addEventListener('DOMContentLoaded', function() {</script>{% endraw %}```-### 4. Purchase (`purchase`)--Track completed purchases on the Shopify "Order status" page (also known as the "Thank You" page).+<Callout type="warn">+ Rybbit limits an event's `properties` to **2048 characters** once serialized to+ JSON, and events that exceed the limit are rejected (not truncated). A full+ per-item `items` array can blow past this on large carts. For carts with many+ line items, send a compact payload β trimmed item fields (e.g. id, quantity,+ price only) or just the aggregate `value`, `currency`, and `transaction_id`.+</Callout>-**1. Navigate to Checkout Settings:**-- Go to **Settings** (bottom left in Admin).-- Click on **Checkout** (or **Checkout and accounts** depending on your Admin version).+### 4. Purchase (`purchase`)-**2. Add the Script:**-- Scroll down to the **Order status page** section.-- In the **Additional scripts** box, paste the following:+Track completed purchases on the Shopify "Thank You" / order status page.-```liquid-{% raw %}{% if first_time_accessed %}-<script type="text/javascript">- if (typeof window.rybbit !== 'undefined' && {{ checkout | json }}) {- const rybbitCheckout = {{ checkout | json }};- let items = [];- rybbitCheckout.line_items.forEach(function(item) {- items.push({- item_id: item.sku || item.variant_id,- item_name: item.product.title, // Access product title via item.product- item_variant: item.variant_title === 'Default Title' ? null : item.variant_title,- price: parseFloat(item.price), // item.price should be line item price- quantity: item.quantity- });- });+<Callout type="warn">+ The old **Order status page > Additional scripts** field has been deprecated. As+ of August 28, 2025 it is view-only (Shopify Plus migration deadline), non-Plus+ stores must migrate by August 26, 2026, and automatic upgrades that began in+ January 2026 remove any remaining `checkout.liquid` / Additional-scripts+ customizations. The supported path for tracking purchases is now+ [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations)+ via a **custom web pixel**.+</Callout>- window.rybbit.event('purchase', {- transaction_id: rybbitCheckout.order_number,- value: parseFloat(rybbitCheckout.total_price),- tax: parseFloat(rybbitCheckout.tax_price),- shipping: parseFloat(rybbitCheckout.shipping_price),- currency: rybbitCheckout.currency,- items: items- });- }-</script>-{% endif %}{% endraw %}+Custom web pixels run in a sandboxed environment, so they **cannot access+`window.rybbit`** on the storefront. Instead, subscribe to the standard+`checkout_completed` event and send the purchase directly to Rybbit's tracking+endpoint with `fetch`.++**1. Create a custom pixel:**+- In your Shopify Admin, go to **Settings > Customer events**.+- Click **Add custom pixel**, give it a name (e.g. `Rybbit`), and click **Add pixel**.++**2. Add the pixel code:**+- Paste the following into the code editor, replacing `YOUR_SITE_ID` with your Site ID, then **Save** and **Connect** the pixel.++```javascript+analytics.subscribe("checkout_completed", (event) => {+ const checkout = event.data.checkout;++ // Keep the payload small β Rybbit rejects event properties over 2048 chars+ // (serialized JSON). Send compact per-item data for large carts.+ const items = (checkout.lineItems || []).map((li) => ({+ id: li.variant?.sku || li.variant?.id,+ qty: li.quantity,+ price: li.variant?.price?.amount,+ }));++ fetch("https://app.rybbit.io/api/track", {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ keepalive: true,+ body: JSON.stringify({+ type: "custom_event",+ site_id: "YOUR_SITE_ID",+ event_name: "purchase",+ // `properties` must be a JSON string (max 2048 chars).+ properties: JSON.stringify({+ transaction_id: checkout.order?.id || checkout.token,+ value: checkout.totalPrice?.amount,+ currency: checkout.currencyCode,+ items: items,+ }),+ }),+ });+});```+**Explanation:**-- `{% raw %}{% if first_time_accessed %}{% endraw %}`: Ensures the script runs only once when the order status page is first loaded, preventing duplicate tracking on page refresh.-- `{{ checkout | json }}`: Provides access to checkout and order data.+- `analytics.subscribe("checkout_completed", ...)` fires once when an order is+ successfully placed, so purchases are tracked without editing `checkout.liquid`.+- The pixel POSTs a `custom_event` straight to Rybbit's `/api/track` endpoint+ because the sandbox has no access to the storefront's `window.rybbit`.+- `properties` is sent as a JSON **string** and must stay under 2048 characters β+ see the note above about trimming large carts.## Important Considerations* **Theme Differences**: Shopify themes can vary significantly. You may need to adjust Liquid object paths (e.g., `product.selected_or_first_available_variant` vs. `current_variant`) and JavaScript selectors based on your specific theme's structure.diff --git a/docs/content/docs/(docs)/guides/squarespace.mdx b/docs/content/docs/(docs)/guides/squarespace.mdxindex cbef7fa3c..13061b099 100644--- a/docs/content/docs/(docs)/guides/squarespace.mdx+++ b/docs/content/docs/(docs)/guides/squarespace.mdx@@ -12,7 +12,7 @@ Integrating Rybbit Analytics with your Squarespace website is straightforward. Y<Step>### Get Your Tracking Script-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:+First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:```html<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>diff --git a/docs/content/docs/(docs)/guides/typo3.mdx b/docs/content/docs/(docs)/guides/typo3.mdxindex 328206430..bfcf8fb94 100644--- a/docs/content/docs/(docs)/guides/typo3.mdx+++ b/docs/content/docs/(docs)/guides/typo3.mdx@@ -46,7 +46,7 @@ page {includeJS {rybbit = https://app.rybbit.io/api/script.jsrybbit.defer = 1- rybbit.data.data-site-id = YOUR_SITE_ID+ rybbit.data-site-id = YOUR_SITE_ID}# ...}@@ -55,6 +55,11 @@ page {This creates a new `<script>` tag, loads the rybbit script and adds the Site IDdata attribute.+Per-include attributes like `data-site-id` require TYPO3 12.1+ (Feature #91499).+On older TYPO3 versions `includeJS` cannot emit `data-*` attributes, so you'll+need a different install method (for example, adding the full `<script>` tag via+`page.headerData`).+Most likely you will already have the line `page = PAGE` somewhere in yourcodebase, this also identifies the file, that is most likely to be your mainTypoScript setup file.@@ -68,7 +73,7 @@ page {includeJS {rybbit = https://app.rybbit.io/api/script.jsrybbit.defer = 1- rybbit.data.data-site-id = YOUR_SITE_ID+ rybbit.data-site-id = YOUR_SITE_ID}}[END]diff --git a/docs/content/docs/(docs)/guides/vue/nuxt.mdx b/docs/content/docs/(docs)/guides/vue/nuxt.mdxindex cc343235c..bc543b70e 100644--- a/docs/content/docs/(docs)/guides/vue/nuxt.mdx+++ b/docs/content/docs/(docs)/guides/vue/nuxt.mdx@@ -160,10 +160,10 @@ From any Vue component within your Nuxt.js application, you can track custom eve<script setup>function trackCustomEvent() {- if (process.client && window.rybbit) { // Ensure running on client and rybbit exists+ if (import.meta.client && window.rybbit) { // Ensure running on client and rybbit existswindow.rybbit.event('nuxt_interaction', { detail: 'User clicked important button' });}}</script>```-Using `process.client` (Nuxt 2) or checking `typeof window !== 'undefined'` (Nuxt 3, or generally) is good practice before accessing `window` if your component might render or execute logic on the server side.+Using `import.meta.client` (Nuxt 3+) or checking `typeof window !== 'undefined'` is good practice before accessing `window` if your component might render or execute logic on the server side. (On Nuxt 2, use the legacy `process.client` flag instead.)diff --git a/docs/content/docs/(docs)/guides/wix.mdx b/docs/content/docs/(docs)/guides/wix.mdxindex a13a5288e..aadfd1bb7 100644--- a/docs/content/docs/(docs)/guides/wix.mdx+++ b/docs/content/docs/(docs)/guides/wix.mdx@@ -12,7 +12,7 @@ Integrating Rybbit Analytics with your Wix website involves adding a custom code<Step>### Get Your Tracking Script-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:+First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:```html<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>diff --git a/docs/content/docs/(docs)/inviting-users.mdx b/docs/content/docs/(docs)/inviting-users.mdxindex 7ff15ca2c..cd3401e5d 100644--- a/docs/content/docs/(docs)/inviting-users.mdx+++ b/docs/content/docs/(docs)/inviting-users.mdx@@ -42,7 +42,7 @@ If you don't enable this option, the member will have access to all sites in you<Step>### Assign teams (optional)-If your organization has [teams](/docs/teams) set up, you can assign the new member to one or more teams during the invitation. When the member accepts the invitation, they will automatically be added to the selected teams.+If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.</Step>@@ -59,7 +59,7 @@ Click the "Invite" button. The user will receive an email with a link to sign upYou can change a member's site access at any time after they've joined your organization.1. Go to **Settings > Organization**-2. Find the member in the list and click on their "Site Access" badge+2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member3. Toggle "Restrict access to specific sites" and select the sites they should have access to4. Click "Save changes"diff --git a/docs/content/docs/(docs)/localhost-tracking.mdx b/docs/content/docs/(docs)/localhost-tracking.mdxindex 9f2f277b0..65dfc3a27 100644--- a/docs/content/docs/(docs)/localhost-tracking.mdx+++ b/docs/content/docs/(docs)/localhost-tracking.mdx@@ -1,72 +1,62 @@---title: Localhost tracking-description: Track analytics during development using API keys+description: How Rybbit handles traffic from localhost during development----import { Steps, Step } from 'fumadocs-ui/components/steps';import { Callout } from 'fumadocs-ui/components/callout';-By default, Rybbit validates tracking events come from your registered domain. During development, you can use API keys to track from localhost.+Rybbit does not restrict tracking to your registered domain β the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.++```html+<script+ defer+ src="https://app.rybbit.io/api/script.js"+ data-site-id="YOUR_SITE_ID">+</script>+```<Callout type="warning">- **Important**: Remember to remove the API key before deploying to production!+ Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.</Callout>-## Localhost Tracking--<Steps>-<Step>-### Generate API Key+## Keeping development traffic out of production data-In your site dashboard: Settings β API Key tab β Generate API Key-</Step>+### Option 1: Use a separate development site-<Step>-### Add to Script+Create a second site in your Rybbit dashboard (e.g. "My App (dev)") and use its site ID during development. Your production site's data stays untouched, and you can still verify events end-to-end.-```html-<script- defer- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- data-api-key="rb_your_api_key_here">-</script>-```-</Step>--<Step>-### Remove for Production--<Callout type="error">- Remove the `data-api-key` attribute before deploying!-</Callout>+```jsx+// Next.js example+export function Analytics() {+ const siteId =+ process.env.NODE_ENV === 'development'+ ? process.env.NEXT_PUBLIC_RYBBIT_DEV_SITE_ID+ : process.env.NEXT_PUBLIC_RYBBIT_SITE_ID;-```html-<!-- Production: NO API KEY -->-<script- defer- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID">-</script>+ return (+ <script+ defer+ src="https://app.rybbit.io/api/script.js"+ data-site-id={siteId}+ />+ );+}```-</Step>-</Steps>-## Best Practice: Environment Variables+### Option 2: Only load the script in production-Use conditional loading to automatically handle development vs production:+If you don't need analytics while developing, skip loading the script entirely outside production:```jsx// Next.js exampleexport function Analytics() {- const isDev = process.env.NODE_ENV === 'development';-+ if (process.env.NODE_ENV !== 'production') return null;+return (<scriptdefersrc="https://app.rybbit.io/api/script.js"data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}- {...(isDev && { 'data-api-key': process.env.NEXT_PUBLIC_RYBBIT_API_KEY })}/>);}@@ -74,32 +64,24 @@ export function Analytics() {```javascript// Vanilla JS example-const script = document.createElement('script');-script.defer = true;-script.src = 'https://app.rybbit.io/api/script.js';-script.setAttribute('data-site-id', 'YOUR_SITE_ID');--// Only add API key in development-if (process.env.NODE_ENV === 'development') {- script.setAttribute('data-api-key', process.env.RYBBIT_API_KEY);+if (process.env.NODE_ENV === 'production') {+ const script = document.createElement('script');+ script.defer = true;+ script.src = 'https://app.rybbit.io/api/script.js';+ script.setAttribute('data-site-id', 'YOUR_SITE_ID');+ document.head.appendChild(script);}--document.head.appendChild(script);```+### Option 3: Filter the traffic instead++If you want the script loaded everywhere but excluded from your stats, use your site's exclusion settings β see [Filtering Traffic](/docs/filter-traffic) and [Hiding Your Own Traffic](/docs/hiding-own-traffic).+## Troubleshooting-**Events not tracking?**-- Verify API key starts with `rb_` and is 35 characters-- Check browser console for errors-- Confirm API key hasn't been revoked--**Accidentally deployed with API key?**-<Steps>-<Step>-### Immediate fix-1. Revoke the API key in dashboard-2. Deploy without the API key-3. Generate new key for development-</Step>-</Steps>\ No newline at end of file+**Events not showing up from localhost?**++- Confirm `data-site-id` matches the site you're looking at in the dashboard+- Check the browser console for errors and the Network tab for `POST` requests to `/api/track`+- Disable ad blockers or privacy extensions β they commonly block analytics scripts on any origin, including localhost+- Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rulesdiff --git a/docs/content/docs/(docs)/managing-your-installation.mdx b/docs/content/docs/(docs)/managing-your-installation.mdxindex 44c05ad5e..ec10a9002 100644--- a/docs/content/docs/(docs)/managing-your-installation.mdx+++ b/docs/content/docs/(docs)/managing-your-installation.mdx@@ -88,7 +88,7 @@ ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;To help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:-- Number of rows in each ClickHouse table+- Number of rows in a few core ClickHouse tables (events and the session replay tables)- Total database size- Your Rybbit version- A hashed instance identifierdiff --git a/docs/content/docs/(docs)/mcp/index.mdx b/docs/content/docs/(docs)/mcp/index.mdxindex b2e19b680..6700f8ee6 100644--- a/docs/content/docs/(docs)/mcp/index.mdx+++ b/docs/content/docs/(docs)/mcp/index.mdx@@ -18,7 +18,7 @@ If your client supports the MCP authorization flow β Claude Code, Codex, Claud### 1. Create an API key1. Open **Settings β Account** in Rybbit.-2. Create a key in the **API Keys** section.+2. Create a key in the **Personal API Keys** section.3. Copy it immediately. Rybbit only shows a new key once.A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate β org admin/owner requirements still apply. Deleting the key revokes the connection.diff --git a/docs/content/docs/(docs)/meta.json b/docs/content/docs/(docs)/meta.jsonindex 84201d895..8ac15bfe4 100644--- a/docs/content/docs/(docs)/meta.json+++ b/docs/content/docs/(docs)/meta.json@@ -6,7 +6,6 @@"pages": ["index","comparison",- "architecture","self-host-vs-cloud","---Usage---","script",diff --git a/docs/content/docs/(docs)/proxy-guide/get-started.mdx b/docs/content/docs/(docs)/proxy-guide/get-started.mdxindex 05fc08f67..478e4f934 100644--- a/docs/content/docs/(docs)/proxy-guide/get-started.mdx+++ b/docs/content/docs/(docs)/proxy-guide/get-started.mdx@@ -45,8 +45,8 @@ This minimal setup enables basic pageview and event tracking, but won't support| Endpoint | Method | Purpose | Cache ||----------|--------|---------|-------|| `/api/script.js` | GET | Main tracking script (minified) | 1 hour |-| `/api/replay.js` | GET | Session replay recording script | 1 hour |-| `/api/metrics.js` | GET | Web Vitals metrics script | 1 hour |+| `/api/replay.js` | GET | Session replay recording script | 1 day |+| `/api/metrics.js` | GET | Web Vitals metrics script | 1 day || `/api/track` | POST | Event tracking endpoint | No cache || `/api/identify` | POST | User identification endpoint | No cache || `/api/session-replay/record/:siteId` | POST | Session replay data upload | No cache |diff --git a/docs/content/docs/(docs)/proxy-guide/next-js.mdx b/docs/content/docs/(docs)/proxy-guide/next-js.mdxindex 92c088a78..43a242780 100644--- a/docs/content/docs/(docs)/proxy-guide/next-js.mdx+++ b/docs/content/docs/(docs)/proxy-guide/next-js.mdx@@ -377,9 +377,9 @@ Next.js automatically caches responses when possible, but you can optimize furthIf deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.**Custom caching headers:**-The Rybbit server sets appropriate cache headers, which Next.js respects:-- Scripts (`.js` files): Cached for 1 hour-- Configuration: Cached for 5 minutes+The Rybbit server sets cache headers on its scripts, which Next.js respects:+- Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)+- Configuration: Not cached by the server (you may cache it for ~5 minutes at your proxy if desired)- Tracking POSTs: Not cached### Server Loaddiff --git a/docs/content/docs/(docs)/roadmap.mdx b/docs/content/docs/(docs)/roadmap.mdxindex 122ebdce7..2d386a634 100644--- a/docs/content/docs/(docs)/roadmap.mdx+++ b/docs/content/docs/(docs)/roadmap.mdx@@ -8,12 +8,8 @@ Rybbit is a quickly growing project. We already have quite a few features, but t## Planned features-- Data export-- Data import from Google Analytics, Plausible, Umami, PostHog, and more-- Custom reports/dashboards-- Stats API+- Data import from Google Analytics, PostHog, and more- More tracking script/SDK integration guides-- Mobile app support- Custom themesOnce again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!\ No newline at end of filediff --git a/docs/content/docs/(docs)/self-host-vs-cloud.mdx b/docs/content/docs/(docs)/self-host-vs-cloud.mdxindex 761320d29..2a6533df7 100644--- a/docs/content/docs/(docs)/self-host-vs-cloud.mdx+++ b/docs/content/docs/(docs)/self-host-vs-cloud.mdx@@ -26,7 +26,7 @@ Rybbit offers two deployment options: a fully-managed [cloud version](https://ry| **Error tracking** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Organizations/Teams** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Pages View** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Web Vitals** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Web Vitals** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Email reports** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth={3}/> (Requires Google OAuth env vars)</span> |diff --git a/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx b/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdxindex 38691f024..07393ae11 100644--- a/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx@@ -30,19 +30,18 @@ Create a new directory for your Rybbit installation and create a `docker-compose```yamlservices:rybbit_clickhouse:- image: clickhouse/clickhouse-server:25.4.2+ image: clickhouse/clickhouse-server:26.3.17.4container_name: rybbit_clickhousevolumes:- ./clickhouse-data:/var/lib/clickhouseconfigs:- source: clickhouse_networktarget: /etc/clickhouse-server/config.d/network.xml- - source: clickhouse_json- target: /etc/clickhouse-server/config.d/enable_json.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml- - source: clickhouse_user_logging- target: /etc/clickhouse-server/config.d/user_logging.xml+ # Profile (user-level) settings are only read from users.d, not config.d+ - source: clickhouse_user_settings+ target: /etc/clickhouse-server/users.d/user_settings.xmlenvironment:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}@@ -76,6 +75,31 @@ services:networks:- internal+ rybbit_redis:+ image: redis:8.6.4-alpine+ container_name: rybbit_redis+ volumes:+ - ./redis-data:/data+ healthcheck:+ test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]+ interval: 3s+ timeout: 5s+ retries: 5+ start_period: 5s+ restart: unless-stopped+ command:+ - redis-server+ - --requirepass+ - ${REDIS_PASSWORD:-changeme}+ - --appendonly+ - "yes"+ - --appendfsync+ - everysec+ - --maxmemory-policy+ - noeviction+ networks:+ - internal+rybbit_backend:image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}container_name: rybbit_backend@@ -89,6 +113,9 @@ services:- POSTGRES_DB=${POSTGRES_DB:-analytics}- POSTGRES_USER=${POSTGRES_USER:-frog}- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}+ - REDIS_HOST=rybbit_redis+ - REDIS_PORT=6379+ - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}- BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}- BASE_URL=${BASE_URL}- DISABLE_SIGNUP=${DISABLE_SIGNUP}@@ -98,6 +125,8 @@ services:condition: service_healthyrybbit_postgres:condition: service_healthy+ rybbit_redis:+ condition: service_healthyhealthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]interval: 3s@@ -136,14 +165,6 @@ configs:<listen_host>0.0.0.0</listen_host></clickhouse>- clickhouse_json:- content: |- <clickhouse>- <settings>- <enable_json_type>1</enable_json_type>- </settings>- </clickhouse>-clickhouse_logging:content: |<clickhouse>@@ -163,11 +184,15 @@ configs:<processors_profile_log remove="remove"/></clickhouse>- clickhouse_user_logging:+ clickhouse_user_settings:content: |<clickhouse><profiles><default>+ <enable_json_type>1</enable_json_type>+ <!-- 26.3+ enables async_insert by default; the backend already+ batches app-side, so keep inserts synchronous -->+ <async_insert>0</async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>diff --git a/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx b/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdxindex 5529b0502..de44db0ec 100644--- a/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx@@ -49,6 +49,9 @@ POSTGRES_DB=analyticsPOSTGRES_USER=changemePOSTGRES_PASSWORD=changeme+# Redis configuration+REDIS_PASSWORD=changeme+# Ports in host:container format (Pangolin needs it like this)HOST_BACKEND_PORT=3001:3001HOST_CLIENT_PORT=3002:3002@@ -83,18 +86,17 @@ services:clickhouse:container_name: clickhouse- image: clickhouse/clickhouse-server:25.4.2+ image: clickhouse/clickhouse-server:26.3.17.4volumes:- clickhouse-data:/var/lib/clickhouseconfigs:- source: clickhouse_networktarget: /etc/clickhouse-server/config.d/network.xml- - source: clickhouse_json- target: /etc/clickhouse-server/config.d/enable_json.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml- - source: clickhouse_user_logging- target: /etc/clickhouse-server/config.d/user_logging.xml+ # Profile (user-level) settings are only read from users.d, not config.d+ - source: clickhouse_user_settings+ target: /etc/clickhouse-server/users.d/user_settings.xmlenvironment:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}@@ -128,6 +130,29 @@ services:ports:- "5432:5432"+ redis:+ image: redis:8.6.4-alpine+ container_name: redis+ volumes:+ - redis-data:/data+ healthcheck:+ test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]+ interval: 3s+ timeout: 5s+ retries: 5+ start_period: 5s+ restart: unless-stopped+ command:+ - redis-server+ - --requirepass+ - ${REDIS_PASSWORD:-changeme}+ - --appendonly+ - "yes"+ - --appendfsync+ - everysec+ - --maxmemory-policy+ - noeviction+backend:image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}container_name: backend@@ -143,6 +168,9 @@ services:- POSTGRES_DB=${POSTGRES_DB:-analytics}- POSTGRES_USER=${POSTGRES_USER:-frog}- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}+ - REDIS_HOST=redis+ - REDIS_PORT=6379+ - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}- BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}- BASE_URL=${BASE_URL}- DISABLE_SIGNUP=${DISABLE_SIGNUP}@@ -153,6 +181,8 @@ services:condition: service_healthypostgres:condition: service_started+ redis:+ condition: service_healthyhealthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]interval: 3s@@ -177,6 +207,7 @@ services:volumes:clickhouse-data:postgres-data:+ redis-data:configs:clickhouse_network:@@ -185,14 +216,6 @@ configs:<listen_host>0.0.0.0</listen_host></clickhouse>- clickhouse_json:- content: |- <clickhouse>- <settings>- <enable_json_type>1</enable_json_type>- </settings>- </clickhouse>-clickhouse_logging:content: |<clickhouse>@@ -212,11 +235,15 @@ configs:<processors_profile_log remove="remove"/></clickhouse>- clickhouse_user_logging:+ clickhouse_user_settings:content: |<clickhouse><profiles><default>+ <enable_json_type>1</enable_json_type>+ <!-- 26.3+ enables async_insert by default; the backend already+ batches app-side, so keep inserts synchronous -->+ <async_insert>0</async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>diff --git a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdxindex 5b8938221..467b4cb5a 100644--- a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx@@ -222,6 +222,7 @@ Rybbit consists of these services:- **backend**: Node.js API server (port 3001)- **postgres**: User data and configuration- **clickhouse**: Analytics data storage+- **redis**: Session tracking and background job queues- **caddy**: Reverse proxy with automatic SSL (optional)## Common Configurations@@ -249,18 +250,17 @@ Here's a modified version of docker-compose that works on Coolify:services:clickhouse:container_name: clickhouse- image: clickhouse/clickhouse-server:25.4.2+ image: clickhouse/clickhouse-server:26.3.17.4volumes:- clickhouse-data:/var/lib/clickhouseconfigs:- source: clickhouse_networktarget: /etc/clickhouse-server/config.d/network.xml- - source: clickhouse_json- target: /etc/clickhouse-server/config.d/enable_json.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml- - source: clickhouse_user_logging- target: /etc/clickhouse-server/config.d/user_logging.xml+ # Profile (user-level) settings are only read from users.d, not config.d+ - source: clickhouse_user_settings+ target: /etc/clickhouse-server/users.d/user_settings.xmlenvironment:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}@@ -302,6 +302,31 @@ services:labels:- traefik.enable=false+ redis:+ image: redis:8.6.4-alpine+ container_name: redis+ volumes:+ - redis-data:/data+ healthcheck:+ test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]+ interval: 3s+ timeout: 5s+ retries: 5+ start_period: 5s+ restart: unless-stopped+ command:+ - redis-server+ - --requirepass+ - ${REDIS_PASSWORD:-changeme}+ - --appendonly+ - "yes"+ - --appendfsync+ - everysec+ - --maxmemory-policy+ - noeviction+ labels:+ - traefik.enable=false+backend:image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}container_name: backend@@ -315,6 +340,9 @@ services:- POSTGRES_DB=${POSTGRES_DB:-analytics}- POSTGRES_USER=${POSTGRES_USER:-frog}- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}+ - REDIS_HOST=redis+ - REDIS_PORT=6379+ - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}- BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}- BASE_URL=${BASE_URL}- DOMAIN_NAME=${DOMAIN_NAME}@@ -326,6 +354,8 @@ services:condition: service_healthypostgres:condition: service_started+ redis:+ condition: service_healthyhealthcheck:test:[@@ -385,14 +415,6 @@ configs:<listen_host>0.0.0.0</listen_host></clickhouse>- clickhouse_json:- content: |- <clickhouse>- <settings>- <enable_json_type>1</enable_json_type>- </settings>- </clickhouse>-clickhouse_logging:content: |<clickhouse>@@ -412,11 +434,15 @@ configs:<processors_profile_log remove="remove"/></clickhouse>- clickhouse_user_logging:+ clickhouse_user_settings:content: |<clickhouse><profiles><default>+ <enable_json_type>1</enable_json_type>+ <!-- 26.3+ enables async_insert by default; the backend already+ batches app-side, so keep inserts synchronous -->+ <async_insert>0</async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>diff --git a/docs/content/docs/(docs)/site-settings.mdx b/docs/content/docs/(docs)/site-settings.mdxindex 2dda3fd75..c042ae253 100644--- a/docs/content/docs/(docs)/site-settings.mdx+++ b/docs/content/docs/(docs)/site-settings.mdx@@ -90,7 +90,19 @@ Block specific IP addresses or ranges from being tracked. Supports:Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).-Both filtering methods work at the server level, ensuring blocked traffic never reaches your analytics database.+### Path Exclusions++Exclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.++### Hostname Exclusions++Exclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.++### User Agent Exclusions++Exclude traffic from user agents containing any of these terms. Matching is a case-insensitive substring (e.g., `HeadlessChrome`). Up to 100 user agent exclusions are allowed.++All of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.## Embedsdiff --git a/docs/content/docs/(docs)/teams.mdx b/docs/content/docs/(docs)/teams.mdxindex b6ec64d75..cc82f754c 100644--- a/docs/content/docs/(docs)/teams.mdx+++ b/docs/content/docs/(docs)/teams.mdx@@ -60,7 +60,7 @@ On the home page, use the team selector in the toolbar to filter the site list b## Assigning Teams During Invitation-When [inviting a new member](/docs/inviting-users), you can optionally assign them to one or more teams. When the member accepts the invitation, they will automatically be added to the selected teams.+When [inviting a new member](/docs/inviting-users), you can optionally assign them to a team. When the member accepts the invitation, they will automatically be added to the selected team.## Permissionsdiff --git a/docs/content/docs/(docs)/track-events.mdx b/docs/content/docs/(docs)/track-events.mdxindex 8001a83fb..543482454 100644--- a/docs/content/docs/(docs)/track-events.mdx+++ b/docs/content/docs/(docs)/track-events.mdx@@ -31,7 +31,7 @@ This approach requires no JavaScript and works on any clickable element.Tracks a custom event with optional properties.-* `eventName` (String): The name of the custom event (max 255 characters).+* `eventName` (String): The name of the custom event (max 256 characters).* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.```javascript@@ -48,7 +48,7 @@ window.rybbit.event("Item Added To Cart", {### `window.rybbit.pageview()`-Tracks a pageview. Useful when `data-track-spa` is set to `"false"` or when you need to manually trigger a pageview.+Tracks a pageview. Useful when automatic SPA navigation tracking is disabled in your site settings, or when you need to manually trigger a pageview.```javascript// Track a pageviewdiff --git a/docs/content/docs/api/api-keys/create-org.mdx b/docs/content/docs/api/api-keys/create-org.mdxnew file mode 100644index 000000000..56cab7a3e--- /dev/null+++ b/docs/content/docs/api/api-keys/create-org.mdx@@ -0,0 +1,302 @@+---+title: Create Organization API Key+description: Programmatically create an API key owned by an organization.+full: true+method: POST+---++import { Callout } from 'fumadocs-ui/components/callout';+import { TypeTable } from 'fumadocs-ui/components/type-table';+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';++<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">+<div>++```+POST /api/organizations/:organizationId/api-keys+```++Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, rate limits, and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.++<Callout type="warn">You must be an **owner or admin** of the target organization. This endpoint accepts your dashboard **session** or an **unrestricted (full-access) user API key** β scoped keys and organization keys are rejected, so an organization key cannot mint other keys.</Callout>++### Path Parameters++<TypeTable+ type={{+ organizationId: {+ description: 'The ID of the organization that will own the key',+ type: 'string',+ required: true,+ },+ }}+/>++### Request Body++<TypeTable+ type={{+ name: {+ description: 'A label for the key',+ type: 'string',+ required: true,+ },+ expiresIn: {+ description: 'Seconds until the key expires. Omit for a key that never expires.',+ type: 'number',+ required: false,+ },+ permissions: {+ description: 'Scope the key to specific `resource: action[]` pairs (e.g. `{ "analytics": ["read"], "goals": ["read", "write"] }`). Omit entirely for a full-access key.',+ type: 'object',+ required: false,+ },+ }}+/>++### Response++Returns the created API key object. The full `key` value carries the `rb_org_` prefix.++<TypeTable+ type={{+ id: {+ description: "The key's identifier",+ type: 'string',+ },+ key: {+ description: 'The secret key value (prefixed with `rb_org_`)',+ type: 'string',+ },+ name: {+ description: 'The label for the key',+ type: 'string',+ },+ start: {+ description: 'A non-secret prefix of the key for display',+ type: 'string',+ },+ prefix: {+ description: 'The key prefix',+ type: 'string',+ },+ referenceId: {+ description: 'The ID of the organization that owns the key',+ type: 'string',+ },+ userId: {+ description: 'The ID of the admin/owner who created the key',+ type: 'string',+ },+ enabled: {+ description: 'Whether the key is currently enabled',+ type: 'boolean',+ },+ expiresAt: {+ description: 'Expiration timestamp, or null if the key never expires',+ type: 'string | null',+ },+ createdAt: {+ description: 'Creation timestamp',+ type: 'string',+ },+ updatedAt: {+ description: 'Last update timestamp',+ type: 'string',+ },+ rateLimitEnabled: {+ description: 'Whether rate limiting is enabled for the key',+ type: 'boolean',+ },+ rateLimitMax: {+ description: 'Requests allowed per window',+ type: 'number',+ },+ rateLimitTimeWindow: {+ description: 'Window length in milliseconds',+ type: 'number',+ },+ }}+/>++**Note:** Additional fields may be present in the response object.++</div>+<div className="flex flex-col gap-4">++<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}>+ <Tab value="cURL">+```bash title="Request"+curl -X POST "https://app.rybbit.io/api/organizations/org_123/api-keys" \+ -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \+ -H "Content-Type: application/json" \+ -d '{"name": "CI pipeline", "expiresIn": 2592000}'+```+ </Tab>+ <Tab value="JavaScript">+```javascript title="Request"+const response = await fetch(+ 'https://app.rybbit.io/api/organizations/org_123/api-keys',+ {+ method: 'POST',+ credentials: 'include',+ headers: {+ 'Content-Type': 'application/json'+ },+ body: JSON.stringify({+ name: 'CI pipeline',+ expiresIn: 2592000+ })+ }+);++const data = await response.json();+```+ </Tab>+ <Tab value="Python">+```python title="Request"+import requests++response = requests.post(+ 'https://app.rybbit.io/api/organizations/org_123/api-keys',+ json={+ 'name': 'CI pipeline',+ 'expiresIn': 2592000+ },+ headers={+ 'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'+ }+)++data = response.json()+```+ </Tab>+ <Tab value="PHP">+```php title="Request"+$ch = curl_init();+curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/org_123/api-keys");+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);+curl_setopt($ch, CURLOPT_POST, true);+curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([+ 'name' => 'CI pipeline',+ 'expiresIn' => 2592000+]));+curl_setopt($ch, CURLOPT_HTTPHEADER, [+ 'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',+ 'Content-Type: application/json'+]);++$response = curl_exec($ch);+curl_close($ch);++$data = json_decode($response, true);+```+ </Tab>+ <Tab value="Ruby">+```ruby title="Request"+require 'net/http'+require 'json'++uri = URI("https://app.rybbit.io/api/organizations/org_123/api-keys")+req = Net::HTTP::Post.new(uri)+req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'+req['Content-Type'] = 'application/json'+req.body = {+ name: 'CI pipeline',+ expiresIn: 2592000+}.to_json++res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }+data = JSON.parse(res.body)+```+ </Tab>+ <Tab value="Go">+```go title="Request"+body := bytes.NewBuffer([]byte(`{+ "name": "CI pipeline",+ "expiresIn": 2592000+}`))+req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/org_123/api-keys", body)+req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")+req.Header.Set("Content-Type", "application/json")++client := &http.Client{}+resp, _ := client.Do(req)+defer resp.Body.Close()++var data map[string]interface{}+json.NewDecoder(resp.Body).Decode(&data)+```+ </Tab>+ <Tab value="Rust">+```rust title="Request"+let client = reqwest::Client::new();+let res = client+ .post("https://app.rybbit.io/api/organizations/org_123/api-keys")+ .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")+ .json(&serde_json::json!({+ "name": "CI pipeline",+ "expiresIn": 2592000+ }))+ .send()+ .await?;++let data: serde_json::Value = res.json().await?;+```+ </Tab>+ <Tab value="Java">+```java title="Request"+HttpClient client = HttpClient.newHttpClient();+String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";+HttpRequest request = HttpRequest.newBuilder()+ .uri(URI.create("https://app.rybbit.io/api/organizations/org_123/api-keys"))+ .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")+ .header("Content-Type", "application/json")+ .POST(HttpRequest.BodyPublishers.ofString(json))+ .build();++HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());+```+ </Tab>+ <Tab value=".NET">+```csharp title="Request"+using var client = new HttpClient();+client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");++var content = new StringContent(+ "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",+ Encoding.UTF8,+ "application/json"+);++var response = await client.PostAsync("https://app.rybbit.io/api/organizations/org_123/api-keys", content);+var data = await response.Content.ReadAsStringAsync();+```+ </Tab>+</Tabs>++<Callout type="warn">The full `key` value is returned **only once**, at creation. Store it securely β it cannot be retrieved again.</Callout>++```json title="Response"+{+ "id": "key_8f3a1b2c4d5e6f7g",+ "key": "rb_org_xxxxxxxxxxxxxxxxxxxx",+ "name": "CI pipeline",+ "start": "rb_org_xxxx",+ "prefix": "rb_org_",+ "referenceId": "org_123",+ "userId": "user_2a9b8c7d6e5f4g3h",+ "enabled": true,+ "expiresAt": "2026-07-25T12:00:00.000Z",+ "createdAt": "2026-06-25T12:00:00.000Z",+ "updatedAt": "2026-06-25T12:00:00.000Z",+ "rateLimitEnabled": true,+ "rateLimitMax": 200,+ "rateLimitTimeWindow": 60000+}+```++<Callout>On Rybbit Cloud, organization API keys require the organization to be on a Standard or Pro plan; free/basic plans receive HTTP 403. Each organization also has a plan-based key-count limit β creating a key past the limit returns HTTP 403.</Callout>++</div>+</div>diff --git a/docs/content/docs/api/api-keys/create.mdx b/docs/content/docs/api/api-keys/create.mdxindex 3a9041d86..4b0517839 100644--- a/docs/content/docs/api/api-keys/create.mdx+++ b/docs/content/docs/api/api-keys/create.mdx@@ -16,9 +16,9 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';POST /api/user/api-keys```-Creates a new API key scoped to your user account (and its organizations).+Creates a new API key scoped to your user account (and its organizations). To create a key owned by an organization instead, see [Create Organization API Key](/docs/api/api-keys/create-org).-<Callout type="warn">This endpoint authenticates with your logged-in dashboard **session**, not an API key β it is how you mint your first key, so you cannot bootstrap a key using another key. Send your session cookie with the request.</Callout>+<Callout type="warn">This endpoint accepts your logged-in dashboard **session** or an **unrestricted (full-access) user API key**. Scoped keys and organization keys are rejected β so a scoped key cannot mint new keys, but a session or full-access key can. Send your session cookie or `Authorization: Bearer` header with the request.</Callout>### Request Bodydiff --git a/docs/content/docs/api/api-keys/meta.json b/docs/content/docs/api/api-keys/meta.jsonindex f0d594fa7..f643fdf3f 100644--- a/docs/content/docs/api/api-keys/meta.json+++ b/docs/content/docs/api/api-keys/meta.json@@ -1,4 +1,4 @@{"title": "API Keys",- "pages": ["create", "list", "update", "delete"]+ "pages": ["create", "create-org", "list", "update", "delete"]}diff --git a/docs/content/docs/api/errors/time-series.mdx b/docs/content/docs/api/errors/time-series.mdxindex 70a288525..5af9655e7 100644--- a/docs/content/docs/api/errors/time-series.mdx+++ b/docs/content/docs/api/errors/time-series.mdx@@ -43,7 +43,7 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plubucket: {description: 'Time bucket size for grouping data',type: 'TimeBucket',- typeDescription: '"minute" | "five_minutes" | "hour" | "day" | "week" | "month"',+ typeDescription: '"minute" | "five_minutes" | "ten_minutes" | "fifteen_minutes" | "hour" | "day" | "week" | "month" | "year"',required: true,},}}diff --git a/docs/content/docs/api/funnels/analyze.mdx b/docs/content/docs/api/funnels/analyze.mdxindex f4ac6c6b5..98181ebee 100644--- a/docs/content/docs/api/funnels/analyze.mdx+++ b/docs/content/docs/api/funnels/analyze.mdx@@ -52,7 +52,7 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (titype: {description: 'Step type',type: 'string',- typeDescription: '"page" | "event"',+ typeDescription: '"page" | "event" | "outbound" | "button_click" | "form_submit" | "copy"',required: true,},value: {diff --git a/docs/content/docs/api/funnels/create.mdx b/docs/content/docs/api/funnels/create.mdxindex be9fe2980..7a1ff4933 100644--- a/docs/content/docs/api/funnels/create.mdx+++ b/docs/content/docs/api/funnels/create.mdx@@ -72,7 +72,7 @@ Creates or updates a saved funnel. If `reportId` is provided, updates the existi<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}><Tab value="cURL">```bash title="Create New Funnel"-curl -X POST "https://app.rybbit.io/api/sites/1/funnels23" \+curl -X POST "https://app.rybbit.io/api/sites/1/funnels" \-H "Authorization: Bearer your_api_key_here" \-H "Content-Type: application/json" \-d '{@@ -89,7 +89,7 @@ curl -X POST "https://app.rybbit.io/api/sites/1/funnels23" \<Tab value="JavaScript">```javascript title="Update Existing Funnel"const response = await fetch(- 'https://app.rybbit.io/api/sites/1/funnels23',+ 'https://app.rybbit.io/api/sites/1/funnels',{method: 'POST',headers: {@@ -117,7 +117,7 @@ const data = await response.json();import requestsresponse = requests.post(- 'https://app.rybbit.io/api/sites/1/funnels23',+ 'https://app.rybbit.io/api/sites/1/funnels',json={'name': 'Onboarding Funnel','steps': [@@ -148,7 +148,7 @@ $body = [];$ch = curl_init();-curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels23');+curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));@@ -168,7 +168,7 @@ $data = json_decode($response, true);require 'net/http'require 'json'-uri = URI('https://app.rybbit.io/api/sites/1/funnels23')+uri = URI('https://app.rybbit.io/api/sites/1/funnels')request = Net::HTTP::Post.new(uri)request['Authorization'] = 'Bearer your_api_key_here'request['Content-Type'] = 'application/json'@@ -202,7 +202,7 @@ body := map[string]interface{}{}jsonBody, _ := json.Marshal(body)-req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels23", bytes.NewBuffer(jsonBody))+req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels", bytes.NewBuffer(jsonBody))req.Header.Set("Authorization", "Bearer your_api_key_here")req.Header.Set("Content-Type", "application/json")@@ -228,7 +228,7 @@ let body = serde_json::json!({let client = reqwest::Client::new();let res = client- .post("https://app.rybbit.io/api/sites/1/funnels23")+ .post("https://app.rybbit.io/api/sites/1/funnels").header("Authorization", "Bearer your_api_key_here").json(&body).send()@@ -253,7 +253,7 @@ String json = """HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder()- .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels23"))+ .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels")).header("Authorization", "Bearer your_api_key_here").header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(json))@@ -284,7 +284,7 @@ var content = new StringContent(Encoding.UTF8,"application/json");-var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/funnels23", content);+var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/funnels", content);var data = await response.Content.ReadAsStringAsync();```</Tab>diff --git a/docs/content/docs/api/funnels/list.mdx b/docs/content/docs/api/funnels/list.mdxindex 50e593eb5..1089bcf45 100644--- a/docs/content/docs/api/funnels/list.mdx+++ b/docs/content/docs/api/funnels/list.mdx@@ -75,14 +75,14 @@ Returns all saved funnels for a site.<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}><Tab value="cURL">```bash title="Request"-curl -X GET "https://app.rybbit.io/api/sites/1/funnels23" \+curl -X GET "https://app.rybbit.io/api/sites/1/funnels" \-H "Authorization: Bearer your_api_key_here"```</Tab><Tab value="JavaScript">```javascript title="Request"const response = await fetch(- 'https://app.rybbit.io/api/sites/1/funnels23',+ 'https://app.rybbit.io/api/sites/1/funnels',{headers: {'Authorization': 'Bearer your_api_key_here'@@ -98,7 +98,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/funnels23',+ 'https://app.rybbit.io/api/sites/1/funnels',headers={'Authorization': 'Bearer your_api_key_here'}@@ -110,7 +110,7 @@ data = response.json()<Tab value="PHP">```php title="Request"$ch = curl_init();-curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels23');+curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer your_api_key_here'@@ -127,7 +127,7 @@ $data = json_decode($response, true);require 'net/http'require 'json'-uri = URI('https://app.rybbit.io/api/sites/1/funnels23')+uri = URI('https://app.rybbit.io/api/sites/1/funnels')request = Net::HTTP::Get.new(uri)request['Authorization'] = 'Bearer your_api_key_here'@@ -150,7 +150,7 @@ import (func main() {client := &http.Client{}- req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/funnels23", nil)+ req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/funnels", nil)req.Header.Set("Authorization", "Bearer your_api_key_here")resp, _ := client.Do(req)@@ -171,7 +171,7 @@ use serde_json::Value;async fn main() -> Result<(), Box<dyn std::error::Error>> {let client = reqwest::Client::new();let response = client- .get("https://app.rybbit.io/api/sites/1/funnels23")+ .get("https://app.rybbit.io/api/sites/1/funnels").header("Authorization", "Bearer your_api_key_here").send().await?;@@ -190,7 +190,7 @@ import java.net.http.HttpResponse;HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder()- .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels23"))+ .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels")).header("Authorization", "Bearer your_api_key_here").GET().build();@@ -210,7 +210,7 @@ client.DefaultRequestHeaders.Authorization =new AuthenticationHeaderValue("Bearer", "your_api_key_here");var response = await client.GetAsync(- "https://app.rybbit.io/api/sites/1/funnels23");+ "https://app.rybbit.io/api/sites/1/funnels");var data = await response.Content.ReadAsStringAsync();```</Tab>diff --git a/docs/content/docs/api/funnels/step-sessions.mdx b/docs/content/docs/api/funnels/step-sessions.mdxindex 91adc87a5..45eeb2ed8 100644--- a/docs/content/docs/api/funnels/step-sessions.mdx+++ b/docs/content/docs/api/funnels/step-sessions.mdx@@ -128,7 +128,7 @@ const data = await response.json();import requestsresponse = requests.post(- 'https://app.rybbit.io/api/sites/1/funnels/2/sessions23',+ 'https://app.rybbit.io/api/sites/1/funnels/2/sessions',params={'mode': 'dropped','page': 1diff --git a/docs/content/docs/api/goals/create.mdx b/docs/content/docs/api/goals/create.mdxindex 424c40a73..4e888c96c 100644--- a/docs/content/docs/api/goals/create.mdx+++ b/docs/content/docs/api/goals/create.mdx@@ -41,7 +41,7 @@ Creates a new goal for tracking conversions.goalType: {description: 'Type of goal',type: 'string',- typeDescription: '"path" | "event"',+ typeDescription: '"path" | "event" | "outbound" | "button_click" | "form_submit" | "copy"',required: true,},config: {@@ -108,7 +108,7 @@ Creates a new goal for tracking conversions.<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}><Tab value="cURL">```bash title="Path Goal"-curl -X POST "https://app.rybbit.io/api/sites/1/goals23" \+curl -X POST "https://app.rybbit.io/api/sites/1/goals" \-H "Authorization: Bearer your_api_key_here" \-H "Content-Type: application/json" \-d '{@@ -123,7 +123,7 @@ curl -X POST "https://app.rybbit.io/api/sites/1/goals23" \<Tab value="JavaScript">```javascript title="Event Goal"const response = await fetch(- 'https://app.rybbit.io/api/sites/1/goals23',+ 'https://app.rybbit.io/api/sites/1/goals',{method: 'POST',headers: {@@ -150,7 +150,7 @@ const data = await response.json();import requestsresponse = requests.post(- 'https://app.rybbit.io/api/sites/1/goals23',+ 'https://app.rybbit.io/api/sites/1/goals',json={'name': 'Signup Complete','goalType': 'path',@@ -177,7 +177,7 @@ $body = [];$ch = curl_init();-curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals23');+curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals');curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));@@ -197,7 +197,7 @@ $data = json_decode($response, true);require 'net/http'require 'json'-uri = URI('https://app.rybbit.io/api/sites/1/goals23')+uri = URI('https://app.rybbit.io/api/sites/1/goals')request = Net::HTTP::Post.new(uri)request['Authorization'] = 'Bearer your_api_key_here'request['Content-Type'] = 'application/json'@@ -225,7 +225,7 @@ body := map[string]interface{}{}jsonBody, _ := json.Marshal(body)-req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/goals23", bytes.NewBuffer(jsonBody))+req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/goals", bytes.NewBuffer(jsonBody))req.Header.Set("Authorization", "Bearer your_api_key_here")req.Header.Set("Content-Type", "application/json")@@ -249,7 +249,7 @@ let body = serde_json::json!({let client = reqwest::Client::new();let res = client- .post("https://app.rybbit.io/api/sites/1/goals23")+ .post("https://app.rybbit.io/api/sites/1/goals").header("Authorization", "Bearer your_api_key_here").json(&body).send()@@ -272,7 +272,7 @@ String json = """HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder()- .uri(URI.create("https://app.rybbit.io/api/sites/1/goals23"))+ .uri(URI.create("https://app.rybbit.io/api/sites/1/goals")).header("Authorization", "Bearer your_api_key_here").header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(json))@@ -298,7 +298,7 @@ var content = new StringContent(Encoding.UTF8,"application/json");-var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/goals23", content);+var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/goals", content);var data = await response.Content.ReadAsStringAsync();```</Tab>diff --git a/docs/content/docs/api/goals/list.mdx b/docs/content/docs/api/goals/list.mdxindex f399c5a34..53bb0de93 100644--- a/docs/content/docs/api/goals/list.mdx+++ b/docs/content/docs/api/goals/list.mdx@@ -172,7 +172,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/goals23',+ 'https://app.rybbit.io/api/sites/1/goals',params={'start_date': '2024-01-01','end_date': '2024-01-31'diff --git a/docs/content/docs/api/insights/journeys.mdx b/docs/content/docs/api/insights/journeys.mdxindex 236ff9b7e..79f2e6d83 100644--- a/docs/content/docs/api/insights/journeys.mdx+++ b/docs/content/docs/api/insights/journeys.mdx@@ -113,7 +113,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/journeys23',+ 'https://app.rybbit.io/api/sites/1/journeys',params={'steps': 4,'limit': 20,diff --git a/docs/content/docs/api/insights/retention.mdx b/docs/content/docs/api/insights/retention.mdxindex 2a8b7766e..740a3e90f 100644--- a/docs/content/docs/api/insights/retention.mdx+++ b/docs/content/docs/api/insights/retention.mdx@@ -127,7 +127,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/retention23',+ 'https://app.rybbit.io/api/sites/1/retention',params={'mode': 'week','range': 90diff --git a/docs/content/docs/api/organizations/list.mdx b/docs/content/docs/api/organizations/list.mdxindex 771ec4427..c2a0bafe5 100644--- a/docs/content/docs/api/organizations/list.mdx+++ b/docs/content/docs/api/organizations/list.mdx@@ -7,6 +7,7 @@ method: GETimport { TypeTable } from 'fumadocs-ui/components/type-table';import { Tab, Tabs } from 'fumadocs-ui/components/tabs';+import { Callout } from 'fumadocs-ui/components/callout';<div className="grid grid-cols-1 xl:grid-cols-2 gap-8"><div>@@ -17,6 +18,8 @@ GET /api/organizationsReturns all organizations the authenticated user is a member of, including all members for each organization. Excludes subscription and billing information. Supports both session cookies and API key (Bearer token) authentication.+<Callout type="warn">The `members` roster is only populated for session-cookie (dashboard) requests. API key / Bearer callers receive `members: []` for every organization β use [GET /organizations/:id/members](/docs/api/organizations/members) to retrieve member data with a key.</Callout>+### ResponseReturns an array of organization objects.diff --git a/docs/content/docs/api/organizations/members.mdx b/docs/content/docs/api/organizations/members.mdxindex 53eade9fb..f04a5122a 100644--- a/docs/content/docs/api/organizations/members.mdx+++ b/docs/content/docs/api/organizations/members.mdx@@ -76,6 +76,14 @@ Each member in the `data` array contains:description: 'User details',type: 'object',},+ siteAccess: {+ description: "The member's site-access restrictions within the organization",+ type: 'object',+ },+ teams: {+ description: 'Teams the member belongs to',+ type: 'array',+ },}}/>@@ -98,6 +106,38 @@ Each member in the `data` array contains:}}/>+#### Site Access Object++<TypeTable+ type={{+ hasRestrictedSiteAccess: {+ description: 'Whether the member is restricted to specific sites',+ type: 'boolean',+ },+ siteIds: {+ description: 'IDs of the sites the member can access (empty when access is not restricted)',+ type: 'array',+ },+ }}+/>++#### Team Object++Each team in the `teams` array contains:++<TypeTable+ type={{+ id: {+ description: 'Team ID',+ type: 'string',+ },+ name: {+ description: 'Team name',+ type: 'string',+ },+ }}+/>+</div><div className="flex flex-col gap-4">@@ -234,7 +274,12 @@ var data = await response.Content.ReadAsStringAsync();"id": "user_xyz789","name": "John Doe","email": "[email protected]"- }+ },+ "siteAccess": {+ "hasRestrictedSiteAccess": false,+ "siteIds": []+ },+ "teams": []},{"id": "member_def456",@@ -246,7 +291,17 @@ var data = await response.Content.ReadAsStringAsync();"id": "user_abc456","name": "Jane Smith","email": "[email protected]"- }+ },+ "siteAccess": {+ "hasRestrictedSiteAccess": true,+ "siteIds": ["456"]+ },+ "teams": [+ {+ "id": "team_789",+ "name": "Marketing"+ }+ ]}]}diff --git a/docs/content/docs/api/organizations/update-member-role.mdx b/docs/content/docs/api/organizations/update-member-role.mdxindex 98f75faaf..77e57e973 100644--- a/docs/content/docs/api/organizations/update-member-role.mdx+++ b/docs/content/docs/api/organizations/update-member-role.mdx@@ -46,18 +46,7 @@ Updates the role(s) assigned to an existing organization member.### Response-Returns the updated member object.--<TypeTable- type={{- member: {- description: 'The member that was updated',- type: 'Member',- },- }}-/>--#### Member Object+Returns the updated member object directly β the fields are at the top level, **not** nested under a `member` key.<TypeTabletype={{@@ -240,13 +229,11 @@ var data = await response.Content.ReadAsStringAsync();```json title="Response"{- "member": {- "id": "mem_7c6d5e4f3g2h",- "userId": "user_5f4g...",- "organizationId": "org_123",- "role": "admin",- "createdAt": "2026-01-10T12:00:00.000Z"- }+ "id": "mem_7c6d5e4f3g2h",+ "userId": "user_5f4g...",+ "organizationId": "org_123",+ "role": "admin",+ "createdAt": "2026-01-10T12:00:00.000Z"}```diff --git a/docs/content/docs/api/overview/metric.mdx b/docs/content/docs/api/overview/metric.mdxindex 3fa9f465f..adea9f2b8 100644--- a/docs/content/docs/api/overview/metric.mdx+++ b/docs/content/docs/api/overview/metric.mdx@@ -80,7 +80,7 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plutypeDescription: 'e.g., "/blog", "Chrome", "US"',},count: {- description: 'Number of sessions for this value',+ description: 'Number of unique sessions for this value. For parameter=event_name, this is the total number of event occurrences instead',type: 'number',},percentage: {@@ -93,6 +93,12 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plutype: 'number',required: false,},+ pageviews_percentage: {+ description: 'Share of total pageviews (for page-related parameters)',+ type: 'number',+ typeDescription: 'Range: 0-100',+ required: false,+ },bounce_rate: {description: 'Bounce rate percentage',type: 'number',diff --git a/docs/content/docs/api/overview/time-series.mdx b/docs/content/docs/api/overview/time-series.mdxindex 604484fae..e61df3946 100644--- a/docs/content/docs/api/overview/time-series.mdx+++ b/docs/content/docs/api/overview/time-series.mdx@@ -39,7 +39,8 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) pludescription: 'Time bucket size for grouping data',type: 'TimeBucket',typeDescription: '"minute" | "five_minutes" | "ten_minutes" | "fifteen_minutes" | "hour" | "day" | "week" | "month" | "year"',- required: true,+ required: false,+ default: 'hour',},}}/>@@ -62,7 +63,7 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plutime: {description: 'Start of the time bucket',type: 'string',- typeDescription: 'ISO 8601 datetime',+ typeDescription: 'Datetime string, "YYYY-MM-DD HH:MM:SS"',},sessions: {description: 'Number of sessions in this bucket',@@ -216,7 +217,7 @@ var data = await response.Content.ReadAsStringAsync();{"data": [{- "time": "2024-01-01T00:00:00.000Z",+ "time": "2024-01-01 00:00:00","sessions": 1250,"pageviews": 3890,"users": 1100,@@ -225,7 +226,7 @@ var data = await response.Content.ReadAsStringAsync();"session_duration": 165.2},{- "time": "2024-01-02T00:00:00.000Z",+ "time": "2024-01-02 00:00:00","sessions": 1420,"pageviews": 4520,"users": 1280,@@ -234,7 +235,7 @@ var data = await response.Content.ReadAsStringAsync();"session_duration": 178.4},{- "time": "2024-01-03T00:00:00.000Z",+ "time": "2024-01-03 00:00:00","sessions": 1380,"pageviews": 4210,"users": 1190,diff --git a/docs/content/docs/api/performance/overview.mdx b/docs/content/docs/api/performance/overview.mdxindex 4a1246168..e9df6c21c 100644--- a/docs/content/docs/api/performance/overview.mdx+++ b/docs/content/docs/api/performance/overview.mdx@@ -106,7 +106,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/performance/overview23',+ 'https://app.rybbit.io/api/sites/1/performance/overview',params={'start_date': '2024-01-01','end_date': '2024-01-31'diff --git a/docs/content/docs/api/performance/time-series.mdx b/docs/content/docs/api/performance/time-series.mdxindex 2c9153a8a..0beac8d6f 100644--- a/docs/content/docs/api/performance/time-series.mdx+++ b/docs/content/docs/api/performance/time-series.mdx@@ -36,10 +36,11 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plu<TypeTabletype={{bucket: {- description: 'Time bucket size for grouping data',+ description: 'Time bucket size for grouping data. Defaults to "hour" when omitted.',type: 'TimeBucket',- typeDescription: '"minute" | "five_minutes" | "hour" | "day" | "week" | "month"',- required: true,+ typeDescription: '"minute" | "five_minutes" | "ten_minutes" | "fifteen_minutes" | "hour" | "day" | "week" | "month" | "year"',+ default: 'hour',+ required: false,},}}/>diff --git a/docs/content/docs/api/sessions/get.mdx b/docs/content/docs/api/sessions/get.mdxindex f6a929c39..05d3af8c3 100644--- a/docs/content/docs/api/sessions/get.mdx+++ b/docs/content/docs/api/sessions/get.mdx@@ -110,7 +110,7 @@ Returns detailed information about a specific session including all events and ptype: {description: 'Event type',type: 'string',- typeDescription: '"pageview" | "custom_event" | "error" | "outbound"',+ typeDescription: '"pageview" | "custom_event" | "error" | "outbound" | "button_click" | "copy" | "form_submit" | "input_change"',},event_name: {description: 'Custom event name (for custom_event type)',diff --git a/docs/content/docs/api/users/info.mdx b/docs/content/docs/api/users/info.mdxindex 974f8a597..b2d1855f6 100644--- a/docs/content/docs/api/users/info.mdx+++ b/docs/content/docs/api/users/info.mdx@@ -131,6 +131,58 @@ Returns detailed information about a specific user, including their profile traitype: 'string',typeDescription: 'ISO 8601 datetime',},+ timezone: {+ description: 'Timezone reported by the browser',+ type: 'string',+ },+ ip: {+ description: 'Last known IP address',+ type: 'string',+ },+ first_referrer: {+ description: 'Referrer URL of the first session',+ type: 'string',+ },+ first_channel: {+ description: 'Acquisition channel of the first session',+ type: 'string',+ },+ first_entry_page: {+ description: 'Entry page path of the first session',+ type: 'string',+ },+ first_utm_source: {+ description: 'UTM source of the first session',+ type: 'string',+ },+ first_utm_medium: {+ description: 'UTM medium of the first session',+ type: 'string',+ },+ first_utm_campaign: {+ description: 'UTM campaign of the first session',+ type: 'string',+ },+ last_referrer: {+ description: 'Referrer URL of the most recent session',+ type: 'string',+ },+ last_channel: {+ description: 'Acquisition channel of the most recent session',+ type: 'string',+ },+ vitals: {+ description: 'p75 Core Web Vitals for this user, or null when no performance data exists',+ type: 'UserVitals | null',+ },+ locations: {+ description: 'Per-location breakdown of sessions',+ type: 'UserLocation[]',+ },+ devices: {+ description: 'Per-device breakdown of sessions',+ type: 'UserDevice[]',+ },linked_devices: {description: 'Devices linked to this identified user',type: 'LinkedDevice[]',@@ -138,6 +190,109 @@ Returns detailed information about a specific user, including their profile trai}}/>+#### UserVitals Object++<TypeTable+ type={{+ lcp_p75: {+ description: 'p75 Largest Contentful Paint (ms)',+ type: 'number | null',+ },+ cls_p75: {+ description: 'p75 Cumulative Layout Shift',+ type: 'number | null',+ },+ inp_p75: {+ description: 'p75 Interaction to Next Paint (ms)',+ type: 'number | null',+ },+ fcp_p75: {+ description: 'p75 First Contentful Paint (ms)',+ type: 'number | null',+ },+ ttfb_p75: {+ description: 'p75 Time to First Byte (ms)',+ type: 'number | null',+ },+ performance_events: {+ description: 'Number of performance events collected',+ type: 'number',+ },+ }}+/>++#### UserLocation Object++<TypeTable+ type={{+ country: {+ description: 'Country code',+ type: 'string',+ },+ region: {+ description: 'Region/state',+ type: 'string',+ },+ city: {+ description: 'City name',+ type: 'string',+ },+ sessions: {+ description: 'Number of sessions from this location',+ type: 'number',+ },+ last_seen: {+ description: 'Most recent activity from this location',+ type: 'string',+ typeDescription: 'ISO 8601 datetime',+ },+ }}+/>++#### UserDevice Object++<TypeTable+ type={{+ device_type: {+ description: 'Device type',+ type: 'string',+ },+ browser: {+ description: 'Browser name',+ type: 'string',+ },+ browser_version: {+ description: 'Browser version',+ type: 'string',+ },+ operating_system: {+ description: 'Operating system name',+ type: 'string',+ },+ operating_system_version: {+ description: 'Operating system version',+ type: 'string',+ },+ screen_width: {+ description: 'Screen width in pixels',+ type: 'number',+ },+ screen_height: {+ description: 'Screen height in pixels',+ type: 'number',+ },+ sessions: {+ description: 'Number of sessions on this device',+ type: 'number',+ },+ last_seen: {+ description: 'Most recent activity on this device',+ type: 'string',+ typeDescription: 'ISO 8601 datetime',+ },+ }}+/>+#### LinkedDevice Object<TypeTable@@ -160,14 +315,14 @@ Returns detailed information about a specific user, including their profile trai<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}><Tab value="cURL">```bash title="Request"-curl -X GET "https://app.rybbit.io/api/sites/123/users/[email protected]/123" \+curl -X GET "https://app.rybbit.io/api/sites/123/users/[email protected]" \-H "Authorization: Bearer your_api_key_here"```</Tab><Tab value="JavaScript">```javascript title="Request"const response = await fetch(- 'https://app.rybbit.io/api/sites/123/users/[email protected]/123',+ 'https://app.rybbit.io/api/sites/123/users/[email protected]',{headers: {'Authorization': 'Bearer your_api_key_here'@@ -183,7 +338,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/123/users/[email protected]/123',+ 'https://app.rybbit.io/api/sites/123/users/[email protected]',headers={'Authorization': 'Bearer your_api_key_here'}@@ -195,7 +350,7 @@ data = response.json()<Tab value="PHP">```php title="Request"$ch = curl_init();-curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/users/[email protected]/123');+curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/users/[email protected]');curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer your_api_key_here'@@ -212,7 +367,7 @@ $data = json_decode($response, true);require 'net/http'require 'json'-uri = URI('https://app.rybbit.io/api/sites/123/users/[email protected]/123')+uri = URI('https://app.rybbit.io/api/sites/123/users/[email protected]')req = Net::HTTP::Get.new(uri)req['Authorization'] = 'Bearer your_api_key_here'@@ -222,7 +377,7 @@ data = JSON.parse(res.body)</Tab><Tab value="Go">```go title="Request"-req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/users/[email protected]/123", nil)+req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/users/[email protected]", nil)req.Header.Set("Authorization", "Bearer your_api_key_here")client := &http.Client{}@@ -237,7 +392,7 @@ json.NewDecoder(resp.Body).Decode(&data)```rust title="Request"let client = reqwest::Client::new();let res = client- .get("https://app.rybbit.io/api/sites/123/users/[email protected]/123")+ .get("https://app.rybbit.io/api/sites/123/users/[email protected]").header("Authorization", "Bearer your_api_key_here").send().await?;@@ -249,7 +404,7 @@ let data: serde_json::Value = res.json().await?;```java title="Request"HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder()- .uri(URI.create("https://app.rybbit.io/api/sites/123/users/[email protected]/123"))+ .uri(URI.create("https://app.rybbit.io/api/sites/123/users/[email protected]")).header("Authorization", "Bearer your_api_key_here").GET().build();@@ -262,7 +417,7 @@ HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ousing var client = new HttpClient();client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");-var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/users/[email protected]/123");+var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/users/[email protected]");var data = await response.Content.ReadAsStringAsync();```</Tab>@@ -295,6 +450,46 @@ var data = await response.Content.ReadAsStringAsync();"screen_height": 1440,"first_seen": "2024-01-15T10:30:00.000Z","last_seen": "2024-01-31T14:22:00.000Z",+ "timezone": "America/Los_Angeles",+ "ip": "203.0.113.42",+ "first_referrer": "https://google.com",+ "first_channel": "Organic Search",+ "first_entry_page": "/pricing",+ "first_utm_source": "google",+ "first_utm_medium": "cpc",+ "first_utm_campaign": "launch",+ "last_referrer": "https://twitter.com",+ "last_channel": "Social",+ "vitals": {+ "lcp_p75": 1240,+ "cls_p75": 0.02,+ "inp_p75": 180,+ "fcp_p75": 890,+ "ttfb_p75": 210,+ "performance_events": 48+ },+ "locations": [+ {+ "country": "US",+ "region": "California",+ "city": "San Francisco",+ "sessions": 10,+ "last_seen": "2024-01-31T14:22:00.000Z"+ }+ ],+ "devices": [+ {+ "device_type": "desktop",+ "browser": "Chrome",+ "browser_version": "120.0.0",+ "operating_system": "macOS",+ "operating_system_version": "14.2",+ "screen_width": 2560,+ "screen_height": 1440,+ "sessions": 9,+ "last_seen": "2024-01-31T14:22:00.000Z"+ }+ ],"linked_devices": [{"anonymous_id": "xyz789ghi012",diff --git a/docs/content/docs/api/users/list.mdx b/docs/content/docs/api/users/list.mdxindex 3c22705b1..def88e790 100644--- a/docs/content/docs/api/users/list.mdx+++ b/docs/content/docs/api/users/list.mdx@@ -43,7 +43,7 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plupage_size: {description: 'Number of results per page',type: 'number',- default: 20,+ default: 100,},sort_by: {description: 'Field to sort by',@@ -191,7 +191,7 @@ const data = await response.json();import requestsresponse = requests.get(- 'https://app.rybbit.io/api/sites/1/users23',+ 'https://app.rybbit.io/api/sites/1/users',params={'page': 1,'page_size': 10,