REST API

The dashboard is a thin React app over a Cloudflare Worker. Everything you do in the UI, you can do from your own code by hitting the same endpoints. This page is the authoritative list, generated from the worker source.

There is no long-lived API key mechanism today. All calls to /api/* require a Clerk session JWT in the Authorization header. The workflow is: obtain a Clerk session, pull its JWT with Clerk’s session.getToken(), and forward it as Authorization: Bearer <jwt>. If you need service account credentials for automation, tell us at enterprise@abtestly.com and we will scope the ask.

Base URL

https://api.abtestly.com

Every authenticated endpoint below is mounted under /api/*. Public endpoints (snippet delivery, event ingestion) are documented in the beacon protocol reference.

Authentication

Authorization: Bearer <clerk-session-jwt>

Verified on every request against Clerk’s JWKS.
Missing or malformed → 401 unauthorized.
Expired → 401 token_expired. Refresh via the Clerk client and retry.
Valid JWT for a user with no access to the requested resource → 403 forbidden.

Cross-site requests are allowed from https://app.abtestly.com only. Server-to-server calls do not need CORS.

Rate limits

100 requests per minute per user across all /api/* endpoints.
Exceeding the limit returns 429 rate_limited with a Retry-After header in seconds.
Public endpoints (/s, /e, /g, /m, /err) have their own limits documented on Rate limits.

Errors

All errors return JSON with a stable machine-readable code and a human-readable message.

{ "error": "not_found", "message": "Experiment not found" }

Common codes: unauthorized, forbidden, not_found, validation_failed, conflict, rate_limited, internal_error.

Endpoint reference

Every path below is under https://api.abtestly.com. Path parameters are marked :name. All POST, PATCH, PUT, and DELETE calls except where noted expect and return JSON.

Account and identity

Method	Path	Purpose
`GET`	`/api/me`	Current user, active org, memberships
`POST`	`/api/onboard`	Complete first-time setup for a new user

Organization membership and permissions

Organization identity itself is managed by Clerk; ABTestly does not expose CRUD on the organization record. Everything below operates on the member roster and per-site permissions inside an org.

Method	Path	Purpose
`GET`	`/api/organizations/:orgId/members`	Roster
`PATCH`	`/api/organizations/:orgId/members/:userId`	Change a member’s role
`POST`	`/api/organizations/:orgId/members/:userId/sites`	Grant the member access to a site, with an optional preset (`full`, `standard`, `viewOnly` or `clear`)
`DELETE`	`/api/organizations/:orgId/members/:userId/sites/:siteId`	Revoke the member’s access to one site
`PUT`	`/api/organizations/:orgId/members/:userId/sites/:siteId/permissions`	Set one member’s permission keys on one site. Below Pro, only one of the four presets or the set already saved is accepted; anything else returns `403 feature_requires_plan`
`PUT`	`/api/organizations/:orgId/members/:userId/permissions/bulk`	Apply one preset (`full`, `standard`, `viewOnly` or `clear`) to every site the member holds
`DELETE`	`/api/organizations/:orgId/members/:userId`	Remove the member from the org
`GET`	`/api/organizations/:orgId/activity`	Activity log for the org
`GET`	`/api/organizations/:orgId/activity/:id`	One activity-log entry

Invitations

Method	Path	Purpose
`GET`	`/api/organizations/:orgId/invitations`	Pending invites for one org
`POST`	`/api/organizations/:orgId/invitations`	Send an invite
`DELETE`	`/api/organizations/:orgId/invitations/:invitationId`	Revoke an invite
`GET`	`/api/invitations/:token`	Public (no auth) — resolve an invitation token to its metadata for the accept page
`POST`	`/api/invitations/accept`	Accept an invitation (uses the token in the request body)

Sites

Method	Path	Purpose
`GET`	`/api/sites`	Sites the caller can see
`POST`	`/api/sites`	Create a site
`GET`	`/api/sites/usage`	Plan, trial state, and site and experiment quota for your organization. Pass `?siteId=` to get the organization that owns that site (`403` if you cannot see it)
`GET`	`/api/sites/:siteId`	One site
`PATCH`	`/api/sites/:siteId`	Update settings
`DELETE`	`/api/sites/:siteId`	Delete site (irreversible)
`GET`	`/api/sites/:siteId/install-status`	Has the snippet ever fired
`GET`	`/api/sites/:siteId/my-access`	Caller’s permission grid for this site
`GET`	`/api/sites/:siteId/collection-health`	Health digest
`GET`	`/api/sites/:siteId/blocked-ips/activity`	Recent blocked-IP hits
`GET`	`/api/sites/:siteId/publish-status`	Publish outbox state
`POST`	`/api/sites/:siteId/publish`	Republish configuration

Experiments

Method	Path	Purpose
`GET`	`/api/experiments`	List; supports pagination, filters, sort
`POST`	`/api/experiments`	Create draft
`GET`	`/api/experiments/:id`	Full experiment payload
`PATCH`	`/api/experiments/:id`	Save edits (draft or running edit-lock rules apply)
`DELETE`	`/api/experiments/:id`	Delete draft
`GET`	`/api/experiments/tags`	Distinct tag list for the org
`GET`	`/api/experiments/digest`	Health-digest bundle for the list view
`GET`	`/api/experiments/:id/collection-health`	Digest for one experiment
`GET`	`/api/experiments/:id/lock-status`	Is another editor holding the lock
`GET`	`/api/experiments/:id/edit-lock`	Acquire the editor lock
`POST`	`/api/experiments/:id/clone`	Clone into a fresh draft with a new salt and key
`POST`	`/api/experiments/:id/reset`	Wipe results, keep configuration
`POST`	`/api/experiments/:id/status`	Start, pause, stop, schedule
`POST`	`/api/experiments/:id/restore`	Restore a deleted experiment
`GET`	`/api/experiments/:id/results`	Computed results (verdict, per-variant, segments)
`GET`	`/api/experiments/:id/variants/:variantKey/revisions`	Stored code versions of one variation, newest first. Metadata only, never code
`GET`	`/api/experiments/:id/variants/:variantKey/revisions/:revision`	One stored code version, with its code

Variant code history

The two read endpoints behind Code history. :variantKey is the variation’s short key, not a row id. Both answer 403 with { "error": "forbidden" } when the experiment does not exist or you cannot read it, before any other check. Anyone who can read the experiment can read its versions, Viewers included. There is no endpoint that writes a version: versions are stored only as a side effect of saving, creating, cloning and Signals drafts. List versions

GET /api/experiments/:id/variants/:variantKey/revisions?limit=20&before=41

Query	Meaning
`limit`	Page size. Defaults to 50. Values above 100 are capped at 100
`before`	A revision number. Returns versions numbered below it. Pass the previous page’s `nextBefore`

A limit or before that is not a positive integer answers 400 with { "error": "validation_error" }.

{
  "revisions": [
    {
      "revision": 40,
      "variantName": "Variation 1",
      "source": "save",
      "experimentStatus": "running",
      "measurementEpoch": 3,
      "resetData": false,
      "jsLen": 1840,
      "cssLen": 312,
      "createdAt": "2026-09-12T10:04:11.000Z",
      "author": { "id": "user_123", "name": null, "email": "dev@example.com" }
    }
  ],
  "nextBefore": 21,
  "current": { "createdAt": "2026-09-12T10:04:11.000Z", "jsLen": 1840, "cssLen": 312 }
}

Field	Meaning
`revision`	The version number, from 1 per variation
`variantName`	The variation’s name when the version was stored
`source`	`save`, `create`, `clone`, `signals_draft`, `baseline` or `recovered`
`experimentStatus`	The experiment’s status when the version was stored
`measurementEpoch`	The experiment’s measurement epoch for that version, or `null`
`resetData`	`true` when the save that stored it also reset the data
`jsLen`, `cssLen`	Code length in Unicode code points
`createdAt`	When the version was stored, ISO 8601
`author`	`{ id, name, email }`, where `name` is the first name or `null`. `null` for a `baseline` or `recovered` version and when the author’s account no longer exists
`nextBefore`	The cursor for the next page, or `null` on the last page
`current`	The variation as it is now: when its row was last written and its code lengths, never its code. `null` when the variation no longer exists. It is on every page

Get one version

GET /api/experiments/:id/variants/:variantKey/revisions/:revision

Returns { "revision": { ... } } with every field above plus jsCode, cssCode and libraryKeys, in load order. A :revision that is not a positive integer, or that this variation does not have, answers 404 with { "error": "not_found" }. Unlike most errors on this page, these three carry only the error code, with no message.

Result exports

Method	Path	Purpose
`POST`	`/api/experiments/:id/events/exports`	Start an async raw-event export
`GET`	`/api/experiments/:id/events/exports/:jobId`	Poll export status
`GET`	`/api/experiments/:id/events/exports/:jobId/download`	Download the CSV once ready

Goals

The goals-library router is mounted under /api/sites, so every path below sits inside a site.

Method	Path	Purpose
`GET`	`/api/sites/:siteId/goals`	Goal library for one site
`POST`	`/api/sites/:siteId/goals`	Create a goal
`PATCH`	`/api/sites/:siteId/goals/:goalId`	Update
`DELETE`	`/api/sites/:siteId/goals/:goalId`	Delete
`POST`	`/api/sites/:siteId/goals/:goalId/clone`	Clone

Audiences

Mounted under /api/sites.

Method	Path	Purpose
`GET`	`/api/sites/:siteId/audiences`	Saved audiences
`POST`	`/api/sites/:siteId/audiences`	Create
`GET`	`/api/sites/:siteId/audiences/:id`	One
`PATCH`	`/api/sites/:siteId/audiences/:id`	Update
`DELETE`	`/api/sites/:siteId/audiences/:id`	Delete

Saved locations

Mounted under /api/sites.

Method	Path	Purpose
`GET`	`/api/sites/:siteId/locations`	Saved URL rulesets
`POST`	`/api/sites/:siteId/locations`	Create
`GET`	`/api/sites/:siteId/locations/:id`	One
`PATCH`	`/api/sites/:siteId/locations/:id`	Update
`DELETE`	`/api/sites/:siteId/locations/:id`	Delete

Mutual exclusion groups

Method	Path	Purpose
`GET`	`/api/sites/:siteId/exclusion-groups`	Groups on this site
`GET`	`/api/sites/:siteId/exclusion-groups/eligible-experiments`	Experiments that can join a group
`GET`	`/api/sites/:siteId/exclusion-groups/:id`	One group
`POST`	`/api/sites/:siteId/exclusion-groups`	Create
`PUT`	`/api/sites/:siteId/exclusion-groups/:id/members`	Set membership (rebuilds slot map)
`POST`	`/api/sites/:siteId/exclusion-groups/:id/activate`	Bump generation, arm the split
`POST`	`/api/sites/:siteId/exclusion-groups/:id/reset`	Reshuffle without touching membership
`PUT`	`/api/sites/:siteId/exclusion-groups/:id/active-members`	Change which members are currently live
`POST`	`/api/sites/:siteId/exclusion-groups/:id/archive`	Archive
`DELETE`	`/api/sites/:siteId/exclusion-groups/:id`	Delete

Billing

Method	Path	Purpose
`GET`	`/api/billing/current`	Current plan, seats, MTU cap, renewal date
`POST`	`/api/billing/checkout-token`	Mint a signed Paddle checkout token to hand to the Paddle.js overlay
`POST`	`/api/billing/portal-session`	Open a Paddle customer-portal session
`POST`	`/api/billing/reactivate`	Reactivate a cancelled subscription within the grace window
`GET`	`/api/billing/verify-checkout-token`	Public (no auth) — Paddle-side verification hop during checkout

Public endpoints

Not authenticated with Clerk. Used by the snippet on the visitor’s device.

Path	Purpose
`/s`	Snippet loader and runtime bundles
`/e`	Exposure and conversion beacons
`/e/validate`	Preview-mode dry-run of a beacon
`/g`	Geo lookup for targeting
`/m`	Snippet telemetry
`/err`	Runtime error reports (first-occurrence dedup)
`/preview-config`	Preview-mode config fetch
`/health`	Liveness ping
`/webhooks/paddle`	Paddle billing webhooks
`/a/*`	Public customer assets on `usercontent.abtestly.com`

The wire format for each of these is on the beacon protocol page.

Not yet published

OpenAPI spec. We are drafting one. Until it ships, treat this page as the source of truth.
Long-lived API keys. No self-serve keys today. If you have a server-side automation use case, tell us at enterprise@abtestly.com.
Webhooks out. Paddle webhooks come in; we do not send outbound webhooks to your infrastructure yet.

If you are building against these and something on this page does not match reality, email support@abtestly.com with the endpoint and the response you got. That is the fastest way for us to fix the doc.

Getting started

Install

Build a test

Target the right visitors

Mutual exclusion groups

Measure

Read results

Methodology

Signals

Preview & QA

Site settings

Team & access

Assets

Integrations

Billing

Trust & compliance

Developer reference

Troubleshooting

Base URL

Authentication

Rate limits

Errors

Endpoint reference

Account and identity

Organization membership and permissions

Invitations

Sites

Experiments

Variant code history

Result exports

Goals

Audiences

Saved locations

Mutual exclusion groups

Billing

Public endpoints

Not yet published

​Base URL

​Authentication

​Rate limits

​Errors

​Endpoint reference

​Account and identity

​Organization membership and permissions

​Invitations

​Sites

​Experiments

​Variant code history

​Result exports

​Goals

​Audiences

​Saved locations

​Mutual exclusion groups

​Billing

​Public endpoints

​Not yet published

Base URL

Authentication

Rate limits

Errors

Endpoint reference

Account and identity

Organization membership and permissions

Invitations

Sites

Experiments

Variant code history

Result exports

Goals

Audiences

Saved locations

Mutual exclusion groups

Billing

Public endpoints

Not yet published