API reference

One REST API over everything the product does: upload a recording, read what the AI concluded, share it, export it, search across it, and receive the reports your own visitors file. JSON in, JSON out, cursor pagination, and RFC 7807 problem responses.

Authentication

Create a key under Dashboard → Developers (Pro and above). Keys are shown once, hashed at rest, scoped to the workspace that created them, and prefixed sr_live_. Send it as a bearer token on every request:

curl https://api.scenerecap.com/v1/recordings \
  -H "Authorization: Bearer sr_live_…"

Conventions

Endpoints

Worked example: upload and analyse

Three calls. Open a session, PUT the parts, then create the recording; the pipeline starts on its own. On a plan with limits, ask first, so a refusal costs one call and not an upload:

# 0. (optional) would the plan accept it? 200, or 402 naming the limit
curl -sX POST https://api.scenerecap.com/v1/recordings/preflight \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"mode":"bug_report","durationSec":48}'

# 1. open a multipart session
curl -sX POST https://api.scenerecap.com/v1/uploads \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"kind":"media","filename":"session.webm","contentType":"video/webm","sizeBytes":8123456}'
# -> { "uploadId": "…", "partSize": 8388608, "parts": [{ "n": 1, "url": "https://…" }] }

# 2. PUT each part to its presigned url, keeping the ETag each one returns
curl -sX PUT "$PART_URL" --data-binary @part-1.bin -D - | grep -i etag

# 3. complete, then create the recording
curl -sX POST https://api.scenerecap.com/v1/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"parts":[{"n":1,"etag":"abc123"}]}'

curl -sX POST https://api.scenerecap.com/v1/recordings \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"uploadId":"'$UPLOAD_ID'","title":"Checkout fails","mode":"bug_report"}'

Poll GET /v1/recordings/:id until status is ready, then read outputs for the bug report, tutorial, explanation or recap.

Worked example: triage the widget Inbox

Duplicates arrive already grouped, so one row can stand for many reports.

curl -s "https://api.scenerecap.com/v1/workspaces/$WS/reports?status=new" \
  -H "Authorization: Bearer $SR_KEY"
# -> reports[0].clusterCount === 5  (five visitors, one bug, one row)

# file it, then mark it triaged with the issue you created
curl -sX POST https://api.scenerecap.com/v1/recordings/$REC/create-issue \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"provider":"linear"}'

curl -sX PATCH https://api.scenerecap.com/v1/reports/$REPORT \
  -H "Authorization: Bearer $SR_KEY" -H "content-type: application/json" \
  -d '{"status":"triaged","issueUrl":"https://linear.app/…"}'

Webhooks

Register a URL under Developers and choose your events: recording.ready, recording.shared, comment.created, check.failed, check.recovered, agent_run.reviewed. Each delivery is a JSON POST carrying X-SceneRecap-Event, X-SceneRecap-Delivery and X-SceneRecap-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body using the secret shown once at creation.

import crypto from "node:crypto";

export function verify(rawBody: Buffer, header: string, secret: string): boolean {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Non-2xx responses are retried with exponential backoff up to three attempts in total (the first delivery plus two retries), and every attempt (status, response body, timing) is visible in the Deliveries panel.

Check alerts fire on a change only: check.failed when a passing check starts failing, and check.recovered when it passes again. A blocked or error run sends neither.

Worked example: refresh a tutorial after a deploy

Call the tutorial’s refresh URL from your deploy pipeline. It takes no API key: sign the request with the tutorial’s own secret, over <timestamp>.<body>, so a captured request cannot be replayed later. Requests more than five minutes old are refused, and every refusal is the same 401.

TS=$(date +%s)
BODY='{"ref":"'$GIT_SHA'"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$TUTORIAL_SECRET" -hex | sed 's/^.* //')

curl -sX POST https://api.scenerecap.com/v1/living-tutorials/$TUTORIAL/refresh \
  -H "content-type: application/json" \
  -H "X-SceneRecap-Timestamp: $TS" \
  -H "X-SceneRecap-Signature: sha256=$SIG" \
  -H "Idempotency-Key: deploy-$GIT_SHA" \
  -d "$BODY"
# a retry with the same Idempotency-Key answers 200 with "replayed": true and costs nothing

Plan limits

Limits are enforced server-side and return 402 with a message naming the limit. API keys require Pro; the reporting widget is a paid add-on; export formats, AI analyses, agent runs (Repro Agent verdicts and Takes draw from one pool), check runs, tutorial refreshes each have their own monthly allowance. See pricing for the current numbers.