API docs by Redocly

Session Replay API (v1)

Download OpenAPI specification:

Session Replay provides an API for capturing bug reports with full context - replays, the sites and teams they belong to, team membership, webhook destinations and authentication - in JSON:API format.

Auth

Obtain an access token

Exchange credentials for a token pair, or exchange a refresh token for a fresh one. grant_type decides which: 'password' (the default) reads email and password, 'refresh_token' reads refresh_token.

Request Body schema: application/json
grant_type
string
Enum: "password" "refresh_token"

Defaults to password

email
string

Password grant only

password
string

Password grant only

name
string

Label for the session being created

refresh_token
string

Refresh token grant only

Responses

Request samples

Content type
application/json
{
  • "grant_type": "password",
  • "email": "string",
  • "password": "string",
  • "name": "string",
  • "refresh_token": "string"
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}

Trade a browser authorization for tokens

Second half of the browser authorization flow. A tool opens /authorize in a browser, is redirected back to its own loopback address with a code, and trades that code here for a token pair. Codes are single use and expire within minutes, must be redeemed against the same redirect_uri they were issued for, and must be presented with the code_verifier whose SHA-256 was sent as the code_challenge on the authorization request.

Request Body schema: application/json
code
required
string

The code the redirect carried back

redirect_uri
required
string

The loopback address the code was issued for

code_verifier
required
string

The secret behind the code_challenge sent to /authorize

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "redirect_uri": "string",
  • "code_verifier": "string"
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}

Revoke the current session

Revokes the session the access token belongs to, so both of its tokens stop working.

Authorizations:
bearer_auth
header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}

Current user

Current browser session user

Who the browser session belongs to. Authenticated by the site's own session cookie rather than a token, because this is what the extension calls once the user has signed in on the site. Passing extension_id hands any replay captured anonymously from that installation to the signed-in user.

query Parameters
extension_id
string

Installation id of the extension asking

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Sign out of the browser session

Ends the site session the extension is riding on. Same cookie authentication as /api/v1/me.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Memberships

List memberships

Every membership of every team the caller belongs to, newest first. A membership with no user and an invite_email is an invitation that has not been accepted yet.

Authorizations:
bearer_auth
query Parameters
page[after]
string

Cursor for pagination (after this cursor)

page[size]
integer

Page size (max 100, default 25)

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    },
  • "links": {
    }
}

Show a membership

Authorizations:
bearer_auth
path Parameters
id
required
string

Membership id

query Parameters
include
string

Include related resources (e.g., 'user,team')

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}

Update a membership

Team admins change roles; a member may update their own membership, which is how an invitation is accepted.

Authorizations:
bearer_auth
path Parameters
id
required
string

Membership id

header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Remove a membership

Team admins remove members; a member may remove their own membership to leave.

Authorizations:
bearer_auth
path Parameters
id
required
string

Membership id

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}

Replays

Answer the domain's questions about a report

What the reporter answered to the questions the domain's owner asks, posted after the report they belong to rather than with it - the panel asks them once the share link is already on screen. Two ways to be allowed: anonymously, with the replay id in the path AND the extension id the report was filed with, both matching the stored report; or signed in, as the report's own submitter. The share token is not a key here - it exists to be forwarded. A report filed through the integration library carries no extension id, so it can only be answered by a signed-in submitter. Posting again replaces the previous answers, so a retry is harmless. Every refusal of the poster is the same 404, whatever was wrong. The whole request may not exceed 64 KB; one that does, or one that declares no length, is refused with 413 and the error code 'answers_too_large'.

path Parameters
id
required
string

The replay's id, as returned when it was created

Request Body schema: application/json
required
extension_id
string

The installation that filed the report. Required unless signed in as its submitter.

required
Array of objects <= 2 items

In the order the questions were asked. A question that was skipped is left out rather than sent empty - an entry with no values stores no row. Required: leaving it out is refused rather than read as an empty list, so a retry whose body was truncated cannot erase what was already stored. An explicit empty list does clear them, which is how an answer is taken back.

Responses

Request samples

Content type
application/json
{
  • "extension_id": "string",
  • "answers": [
    ]
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Create replay (screenshot or video)

Create a new replay. Supports three authentication methods: Site API Key (recommended), JWT token, or anonymous. Two types supported: 'screenshot' for quick snapshots with basic metadata, 'video' for full session recordings with extended metadata. The whole request may not exceed 600 MB. One that does, or one that declares no length, is refused with 413 and the error code 'replay_too_large' before anything is stored, and the accompanying detail is written to be shown to the person reporting the bug.

header Parameters
X-Site-API-Key
string

Site API key for authentication (get from Site Settings)

Authorization
string

JWT Bearer token (alternative to API key)

Request Body schema:

ZIP file containing metadata.json and recording file (RECOMMENDED - uploads directly to S3, can be reprocessed)

file

Responses

Request samples

Content type
No sample

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

List replays

Get a paginated list of replays (requires authentication - returns user's own replays and team replays)

Authorizations:
bearer_auth
query Parameters
page[after]
string

Cursor for pagination (after this cursor)

page[before]
string

Cursor for reverse pagination (before this cursor)

page[size]
integer

Page size (max 100, default 25)

filter[replay_type]
string
Enum: "screenshot" "video"

Filter by type

filter[resolution_status]
string
Enum: "pending" "in_progress" "resolved" "wont_fix"

Filter by status

include
string

Include related resources (e.g., 'site,submitter')

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    },
  • "links": {
    }
}

Show replay

Get a specific replay (requires authentication)

Authorizations:
bearer_auth
path Parameters
id
required
string

Replay ID

query Parameters
include
string

Include related resources (e.g., 'site,submitter')

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update replay

Update a replay (requires team membership or ownership). An update may carry a recording, so it takes the same 600 MB ceiling the upload does and is refused the same way: 413 with the error code 'replay_too_large'.

Authorizations:
bearer_auth
path Parameters
id
required
string

Replay ID

header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

Delete replay

Delete a replay (requires team membership or ownership)

Authorizations:
bearer_auth
path Parameters
id
required
string

Replay ID

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}

Extract a frame from a replay's recording

Return a single still from the replay's screen recording at the offset given, extracted per request and never stored. The image is JPEG, scaled down to the requested width and never scaled up past the recording's own size. Screenshot reports have no recording and are refused.

Authorizations:
bearer_auth
path Parameters
id
required
string

Replay ID

query Parameters
offset_ms
required
integer

Moment in the recording, in milliseconds from its start - the same unit the replay's own duration and log offsets use

width
integer

Widest the frame may be, in pixels (64-2560, default 1280). A narrower recording is returned at its own width.

header Parameters
Authorization
string

Bearer token

Responses

Sites

List sites

The sites of every team the caller owns or belongs to, newest first.

Authorizations:
bearer_auth
query Parameters
page[after]
string

Cursor for pagination (after this cursor)

page[size]
integer

Page size (max 100, default 25)

q
string

Free text search

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    },
  • "links": {
    }
}

Claim a site

Claims a domain for the caller's own team. Claiming a domain is a paid feature, so a team with no plan, or one already at its domain limit, is refused.

Authorizations:
bearer_auth
header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Show a site

Authorizations:
bearer_auth
path Parameters
id
required
string

Site id

query Parameters
include
string

Include related resources (e.g., 'team')

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}

Update a site

Team admins only. Retention and tier are not settable here - both follow the team's plan.

Authorizations:
bearer_auth
path Parameters
id
required
string

Site id

header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Delete a site

Team owner only. Deletes the site's replays with it.

Authorizations:
bearer_auth
path Parameters
id
required
string

Site id

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}

Teams

List teams

The teams the caller owns or is a member of, newest first.

Authorizations:
bearer_auth
query Parameters
page[after]
string

Cursor for pagination (after this cursor)

page[size]
integer

Page size (max 100, default 25)

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    },
  • "links": {
    }
}

Create a team

The caller becomes the team's owner.

Authorizations:
bearer_auth
header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Show a team

Authorizations:
bearer_auth
path Parameters
id
required
string

Team id

query Parameters
include
string

Include related resources (e.g., 'owner,sites')

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}

Update a team

Team admins only.

Authorizations:
bearer_auth
path Parameters
id
required
string

Team id

header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Delete a team

Team owner only.

Authorizations:
bearer_auth
path Parameters
id
required
string

Team id

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}

Webhook destinations

Subscribe a webhook to events

Registers a URL of yours against a team you administer. Name the team with team_id, or leave it out and the destination is attached to your personal team. The response carries the signing key once, on create: every delivery is signed with it and there is no second chance to read it over the API.

Authorizations:
bearer_auth
header Parameters
Authorization
string

Bearer token

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "meta": {
    }
}

Unsubscribe a webhook

Removes a destination of a team you administer. A destination belonging to any other team answers as though it does not exist.

Authorizations:
bearer_auth
path Parameters
id
required
string

Webhook destination id

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": { },
  • "meta": {
    }
}