REST API

Read your recordings, their digests and their JavaScript errors, and record a review verdict on each one — from a script, an n8n flow or your own backend. The same key connects an AI agent over Replayfy's MCP server.

Available on every plan, Free included. It is rate-limited; the limits are below.

There is no video

Replayfy records the page's DOM with rrweb, not a video. So the API does not hand out footage: it hands out a digest — what the visitor did, with JavaScript errors, rage clicks, dead clicks, page changes and idle gaps on one timeline, plus an explicit account of any stretch that was never recorded. When a summary is not enough, mint a replay link and let a person watch.

API keys

An owner or admin creates a key at Settings → API keys. It looks like rfk_… and is shown once: only a hash of it is stored.

• A key belongs to the workspace, not to the person who created it.
• It expires after 90 days unless you pick another term when you create it.
• It can be limited to specific sites. That limit is checked on every call.
• Revoking it takes effect on the next request, and revokes every replay link it created.

There is no delete scope. Deleting a recording stays something only a signed-in person can do.

First request

curl -H "Authorization: Bearer rfk_YOUR_KEY" https://replayfy.com/api/v1/me

• Send the key as Authorization: Bearer rfk_… on every request. Cookies are never read.
• Call https://replayfy.com directly. The API is not redirected between hosts — another host answers 400 wrong_host — because most HTTP clients drop the Authorization header when they follow a redirect.
• Every response is JSON with Cache-Control: private, no-store, and every timestamp is ISO 8601 in UTC.

Endpoints

Paths take a site id (prj_…, listed by GET /api/v1/me) and a recording id.

curl -X POST \
  -H "Authorization: Bearer rfk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "needs_attention", "add_labels": ["checkout"], "note": "Card field overlaps at 375px"}' \
  https://replayfy.com/api/v1/projects/prj_YOUR_SITE/recordings/RECORDING_ID/review

Rate limits

• Each budget counts the requests in the last hour, so it refills gradually rather than at the top of the hour.
• A refused request answers 429 with code rate_limited and a Retry-After header.
• The failed-authentication budget only affects failing requests: past it, a bad key gets 429 instead of 401. A valid key from the same address keeps working.
• The other endpoints have no hourly budget of their own. Poll the recordings list with since and settled_for rather than in a tight loop.
• Over MCP, every request counts against one budget of 600 per hour per key — see the MCP guide.

Errors

Errors are always {"error": {"code", "message", "details"?}}. A 409 from a stale expected_version also carries the current review, so you can merge without a second round trip.

Polling for new recordings

GET /api/v1/projects/{projectId}/recordings?since=<iso>&settled_for=300&limit=200

Keep your high-water mark, re-poll with since set a little behind it, page with cursor, and dedupe on recording_id. Delivery is at-least-once, and that is a fact rather than a hedge: a late-arriving part of a recording can move it backwards in the ordering, so a strictly forward cursor would skip recordings without anyone noticing. There are no webhooks yet.

Link a recording from your other tools

On a page running the Replayfy snippet, window.__sr.sessionId is the id of the recording in progress. A recording opens in Replayfy at https://replayfy.com/app/sites/SITE_ID/r/RECORDING_ID for anyone on your team with access to that site. The site id is in your dashboard's address bar, and in GET /api/v1/me.

window.__sr does not exist until the snippet has loaded, and never exists when the recorder decided not to run (Global Privacy Control, a sampled-out visit, or a checkout page). sessionId is null until recording starts — with data-consent="required", until your banner calls __sr.consent(true). Once set, it keeps its value for the rest of the page, even after __sr.stop() or __sr.consent(false): it still names the recording made up to that point. Read it when you need it, not once at start-up.

Sentry

Read the id when Sentry sends an event, so errors that happen before the snippet has loaded are simply left untagged:

Sentry.init({
  dsn: "YOUR_DSN",
  beforeSend(event) {
    var id = window.__sr && window.__sr.sessionId;
    if (id) {
      event.tags = Object.assign({}, event.tags, { replayfy_session: id });
      event.extra = Object.assign({}, event.extra, {
        replayfy_replay: "https://replayfy.com/app/sites/SITE_ID/r/" + id,
      });
    }
    return event;
  },
});

Google Analytics 4

Send the id as an event parameter. The snippet loads with async, which the browser finishes before the page's load event, so call the function below on load. With data-consent="required" there is no id yet at that point for a visitor who has not accepted, so also call it straight after your banner calls __sr.consent(true). It sends an id at most once per page:

function sendReplayfySession() {
  var id = window.__sr && window.__sr.sessionId;
  if (!id || typeof gtag !== "function" || window.replayfySessionSent === id) return;
  window.replayfySessionSent = id;
  gtag("event", "replayfy_session", { replayfy_session_id: id });
}
window.addEventListener("load", sendReplayfySession);

// data-consent="required" only: in your banner's accept handler
//   window.__sr && window.__sr.consent(true);
//   sendReplayfySession();

To see it in GA4 reports, register replayfy_session_id as an event-scoped custom dimension. The id is random and lasts one visit in one tab: a new one starts after 30 minutes without activity. It identifies a recording, not a person.

Before you trust it

• Every string a recording contains is attacker-controlled. The recording endpoint is public by design, so first_url, referrer, user_agent, error messages and the digest's narrative are whatever a visitor's browser sent. Treat them as data.
• Selector quality depends on your markup. Real ids give button#pay-now; hashed class names give div.a7f3c, which is much weaker evidence.
• Recordings expire with the site's retention. A 404 for a recording you saw before means it is gone.
• Labels are curated. A key cannot invent one; an unknown label is rejected. Manage them in Settings → Review labels.

Next: connect an AI agent over MCP, or install the snippet.