Skip to content

REST API ​

Everything the dashboard does goes through one REST API under /api/v1, so scripts, other servers and the mobile app can do the same: list and replay sessions, read heatmaps and funnels, manage sites, surveys, A/B tests and alerts. Requests and answers are JSON; you authenticate with a Bearer token.

10 minutesDevelopersSingle user · SaaS
your-site.com/tokens
Developers › API tokens: one token per site, script or app, each with only the access it needs.Developers › API tokens: one token per site, script or app, each with only the access it needs.
Developers › API tokens: one token per site, script or app, each with only the access it needs.

Base URL ​

https://<your Replora server>/api/v1

Every path in the reference is relative to it, e.g. GET /api/v1/sites. Send Accept: application/json (and Content-Type: application/json with a body).

The full description is an OpenAPI 3.1 file: download openapi.yaml. Import it into Postman, Insomnia or a client generator.

Authentication ​

There are two ways in, to the same endpoints.

Bearer tokens (scripts, servers, the mobile app) ​

Option 1: create a token in the dashboard. Developers › API tokens › Create token:

FieldWhat it does
NameWhere it will be used, e.g. "Company website" or "iOS app" (up to 120 characters).
AccessFull access (*: everything your account can do) or single abilities (see below).
ExpiresNever expires, 30 days, 90 days or 1 year (the API accepts 1–3650 days).
Your passwordConfirms it's you before a new key to your account is created.

The token is shown only once: store it somewhere safe (a password manager, your server's environment variables). The list shows each token's access, last use, expiry and creation date; Revoke stops it at once.

Option 2: sign in from your client with a device_name. The answer carries a full-access token named after the device:

sh
curl -X POST https://replora.example.com/api/v1/auth/login \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…","device_name":"Reporting script"}'
json
{ "data": { "id": 1, "name": "Ada Lovelace", "email": "[email protected]", "…": "…" },
  "token": "3|r8Jw…", "token_type": "Bearer" }

Accounts with two-factor sign-in also send code (the authenticator's 6-digit code or a recovery code); without it the answer is a 422 on code after the right password. POST /auth/logout revokes the token used.

Then send the token on every request:

sh
curl https://replora.example.com/api/v1/sites \
  -H "Authorization: Bearer 3|r8Jw…" -H "Accept: application/json"

Abilities ​

AbilityAllows
*Everything the person may do (shown as Full access).
recordings:readList sites and sessions, replay recordings, and read the modules' reports (heatmaps, funnels, events, errors, forms, insights, surveys, A/B tests, alerts…).
recordings:writeCreate, change and delete sites and recordings, and the modules' objects (funnels, surveys, A/B tests, alerts…).

Modules declare their abilities in module.json; GET /tokens lists those available on your installation in meta.abilities. Routes about the person, the account and the installation (profile, team, tokens, users, settings, billing, integrations) need the dashboard session or a full-access token: a limited token gets 403, so it can never make itself a full-access token.

A token also has the person's role in the account: a viewer may read but change nothing; billing is changed by managers only. Suspended accounts are refused at once (403).

The dashboard on the same site signs in with the same POST /auth/login (without device_name) and gets a session cookie instead of a token (Laravel Sanctum's SPA mode). Changing requests send X-XSRF-TOKEN with the XSRF-TOKEN cookie's value. Only hosts listed in SANCTUM_STATEFUL_DOMAINS get sessions; see Environment. Don't use this from other sites: use tokens.

Errors ​

Every error has the same JSON shape:

json
{ "message": "The name field is required.", "errors": { "name": ["The name field is required."] } }

errors (field → messages) is only present with 422.

StatusMeaning
401No or invalid token / session ({"message": "Unauthenticated."}).
403Signed in but not allowed: missing ability, limited token on an account route, viewer role, a plan that doesn't include the feature ("Your plan doesn’t include …"), a suspended account.
404Not found. Another account's records answer 404 exactly like missing ones ({"message": "Not found."}), and so do endpoints of modules that aren't enabled.
422Validation failed; see errors.
429Rate limit hit; wait for Retry-After seconds.
503Maintenance mode (installation administrators keep working).

Messages are in the person's language (the dashboard's languages), so match on status and field names, not on message text.

Paging ​

Lists take ?page= and ?per_page= (1–100, default 25) and answer with meta:

sh
curl "https://replora.example.com/api/v1/sites/1/sessions?per_page=50&page=2&sort=-duration" \
  -H "Authorization: Bearer $REPLORA_TOKEN" -H "Accept: application/json"
json
{
  "data": [ { "id": "1f0c…", "started_at": "2026-11-20T10:12:04+00:00", "duration_ms": 312000, "…": "…" } ],
  "meta": { "current_page": 2, "last_page": 7, "per_page": 50, "total": 331 }
}

Some reports have their own limits instead (e.g. the sessions CSV export: at most 10 000 rows; the events list: the 200 most frequent names).

Rate limits ​

LimitApplies toPer
120 requests a minuteEvery API route, with a token (or without signing in)Person (or IP address)
600 requests a minuteEvery API route from the dashboard's sessionPerson
5 a minute per email and address, 20 a minute per emailSign-in, sign-up, invitationsEmail / IP
6 a minutePassword reset, account deletion, data export, license changesIP / person
10–30 a minuteSingle expensive actions: AI summaries (20), Ask AI (20), alert tests (10), billing actions (10), administrator CSV exports (10), recording downloads (30), survey changes (60)Person
120 a minutePublic share links (/shared/{token})IP

Tracker endpoints (not part of the API) have their own limits: RECORDINGS_INGEST_PER_MINUTE (600 a minute per IP) for recordings and rules, 120 a minute per IP for surveys and A/B tests. The full list is in Plan limits & file types.

Editions and modules ​

GET /app is public and tells a client what it talks to:

sh
curl https://replora.example.com/api/v1/app -H "Accept: application/json"
json
{
  "data": {
    "name": "Replora",
    "version": "1.0.0",
    "api_version": "v1",
    "edition": { "mode": "saas", "signup": true, "google": false },
    "modules": ["Alerts", "Errors", "Events", "Experiments", "Forms", "Funnels", "Heatmaps", "…"],
    "realtime": { "transport": "polling", "poll_seconds": 5, "websocket": null }
  }
}

Endpoints of a module that isn't enabled, or belongs to the other edition (e.g. /plans and /billing outside the SaaS edition), answer 404. Endpoints behind a plan feature answer 403 when the account's plan doesn't include it.

Versioning ​

The version is in the path (/api/v1). Within v1, endpoints and fields are only added, never removed or renamed; a breaking change would come as /api/v2 next to v1. GET /app → api_version says which version the server speaks; version is the Replora release.

Live updates ​

The live-visitors view and other live data are available two ways, announced by GET /app → realtime:

  • polling: call GET /sites/{site}/live every poll_seconds, sending the last meta.cursor as since;
  • websocket: Laravel Reverb (Pusher protocol) with the websocket settings; private channels are authorised at POST /broadcasting/auth with the same token or session.

Endpoint groups ​

The reference is generated from the OpenAPI file, one page per group:

GroupEndpointsWhat it covers
App3Edition, version, modules; WebSocket channel authorisation
Auth7Sign-in, two-factor step, sign-up, invitations, sign-out
Account26Profile, password, two-factor, Google account, data export, account, tokens
Team5Members, invitations, roles
Integrations3HubSpot connection
Administration15Users, overview, installation settings (administrators)
Sites5Websites: create, read, change, delete
Recordings20Sessions, filters, replay events, share links, downloads, live view
AI summaries14Session summaries, plain-words search, Ask AI, site digests
Heatmaps2Pages with heatmap data, a page's clicks, scrolling and movement
Funnels9Funnels, reports, sessions per step
Events2Custom events and their occurrences
Insights4Frustration, journeys, elements
A/B tests6Tests and their results
Surveys12Surveys, designs, results and answers
Alerts7Alerts, test sends, matches
Errors6JavaScript errors grouped by cause
Forms4Form analytics
System13Version, license, updates, service status, maintenance (administrators)
Announcements7What's new posts
Help12Help center articles and the help chat
Website13SaaS public website settings
Affiliates11SaaS affiliate program
Support tickets28SaaS support desk
Plans & billing14SaaS plans, subscriptions, invoices

Examples ​

Create a website and get its snippet:

sh
curl -X POST https://replora.example.com/api/v1/sites \
  -H "Authorization: Bearer $REPLORA_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"name":"Shop","allowed_domains":["shop.example"]}'

The answer's data.snippet is the <script> tag to put on the site; data.public_key is its key.

Sessions with a rage click from mobile visitors in the last week:

sh
curl -G https://replora.example.com/api/v1/sites/1/sessions \
  -H "Authorization: Bearer $REPLORA_TOKEN" -H "Accept: application/json" \
  --data-urlencode "has[]=rage_clicks" --data-urlencode "device=mobile" --data-urlencode "from=2026-11-13"

Tag a session from your back office:

sh
curl -X PATCH https://replora.example.com/api/v1/sites/1/sessions/1f0c2b9e-7a4d-4c1e-9d55-0f3a8e7b6c21 \
  -H "Authorization: Bearer $REPLORA_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"starred":true,"notes":"Customer called about this checkout","tags":{"ticket":"4711"}}'

In JavaScript (Node 18+):

js
const res = await fetch('https://replora.example.com/api/v1/sites', {
  headers: { Authorization: `Bearer ${process.env.REPLORA_TOKEN}`, Accept: 'application/json' },
});
if (!res.ok) throw new Error((await res.json()).message);
const { data: sites } = await res.json();

Replora: see what your visitors see.