# Session Replay Settings

> Configure session replay capture. Create, list, update, and delete session replay settings in your Ours Privacy account.

Source: https://docs.oursprivacy.com/docs/platform-api/replay-settings

Configure session replay settings. Create, list, update, and delete replay settings in your account.

## GET /rest/v1/replay-settings

List the replay configurations on this account. Supports cursor pagination via `limit` and `cursor`. Replay settings control which domains may capture session replays and where the capture script is hosted. Requires API-key scope or current OAuth user permission: replaySettings:list

Request URL: `GET https://app.oursprivacy.com/rest/v1/replay-settings`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer \| null | No | Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100. Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100. |
| `cursor` | query | string | No | Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. |

### Responses

- `200`: List of replay settings
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].id` | string | Yes | Stable identifier (UUID) for this replay configuration. |
| `entities[].name` | string | Yes | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `entities[].status` | string | Yes | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`. |
| `entities[].createdAt` | string | Yes | ISO-8601 timestamp when this configuration was created. |
| `entities[].updatedAt` | string \| null | No | ISO-8601 timestamp of the most recent update, or null if never updated. |
| `entities[].whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |
| `entities[].customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `entities[].pixel` | string | Yes | Server-assigned public replay token used by the browser SDK to start session replay capture. |
| `pagination` | object | Yes |  |
| `pagination.nextCursor` | string \| null | No |  |
| `pagination.hasMore` | boolean | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## POST /rest/v1/replay-settings

Create the replay configuration for this account. Each account is limited to one replay configuration — calls made when one already exists return HTTP 409 with the reason in the response `error` field. Publish with `POST /versions` for the configuration to take effect. Requires API-key scope or current OAuth user permission: replaySettings:create

Request URL: `POST https://app.oursprivacy.com/rest/v1/replay-settings`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `name` | string \| null | No | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `status` | string \| null | No | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`, `null`. |
| `whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |

### Responses

- `200`: Created replay setting
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `409`: Conflict — account already has a replay configuration. Each account is limited to one. Reason is in the response `error` field.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isSuccess` | boolean | Yes |  |
| `cause` | string \| null | No |  |
| `replaySettings` | object \| null | No |  |
| `replaySettings.id` | string | Yes | Stable identifier (UUID) for this replay configuration. |
| `replaySettings.name` | string | Yes | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `replaySettings.status` | string | Yes | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`. |
| `replaySettings.createdAt` | string | Yes | ISO-8601 timestamp when this configuration was created. |
| `replaySettings.updatedAt` | string \| null | No | ISO-8601 timestamp of the most recent update, or null if never updated. |
| `replaySettings.whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |
| `replaySettings.customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `replaySettings.pixel` | string | Yes | Server-assigned public replay token used by the browser SDK to start session replay capture. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/replay-settings/{id}

Fetch a single replay configuration by ID, including its whitelisted domains, custom domain, and public replay pixel token. Returns HTTP 404 when it does not exist. Requires API-key scope or current OAuth user permission: replaySettings:find

Request URL: `GET https://app.oursprivacy.com/rest/v1/replay-settings/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Replay Settings details
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Stable identifier (UUID) for this replay configuration. |
| `name` | string | Yes | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `status` | string | Yes | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`. |
| `createdAt` | string | Yes | ISO-8601 timestamp when this configuration was created. |
| `updatedAt` | string \| null | No | ISO-8601 timestamp of the most recent update, or null if never updated. |
| `whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |
| `customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `pixel` | string | Yes | Server-assigned public replay token used by the browser SDK to start session replay capture. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## PATCH /rest/v1/replay-settings/{id}

Update one or more fields on an existing replay configuration. Only the fields you send are changed; omitted fields keep their current value. Note that `whitelistDomains` is replaced wholesale (not merged with the existing list). Null leaves `name`, `status`, and `whitelistDomains` unchanged; null clears `customDomain`. Publish with `POST /versions` for changes to take effect. Requires API-key scope or current OAuth user permission: replaySettings:update

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/replay-settings/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `name` | string \| null | No | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `status` | string \| null | No | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`, `null`. |
| `whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |

### Responses

- `200`: Updated replay setting
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isSuccess` | boolean | Yes |  |
| `cause` | string \| null | No |  |
| `replaySettings` | object \| null | No |  |
| `replaySettings.id` | string | Yes | Stable identifier (UUID) for this replay configuration. |
| `replaySettings.name` | string | Yes | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `replaySettings.status` | string | Yes | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`. |
| `replaySettings.createdAt` | string | Yes | ISO-8601 timestamp when this configuration was created. |
| `replaySettings.updatedAt` | string \| null | No | ISO-8601 timestamp of the most recent update, or null if never updated. |
| `replaySettings.whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |
| `replaySettings.customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `replaySettings.pixel` | string | Yes | Server-assigned public replay token used by the browser SDK to start session replay capture. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## DELETE /rest/v1/replay-settings/{id}

Delete the replay configuration from the draft. Publish with `POST /versions` for capture to stop on all whitelisted domains. Returns the same HTTP 404 when the configuration is missing or inaccessible. Requires API-key scope or current OAuth user permission: replaySettings:delete

Request URL: `DELETE https://app.oursprivacy.com/rest/v1/replay-settings/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | Yes | Replay configuration id, as returned by the list operation. Replay configuration id, as returned by the list operation. |

### Responses

- `200`: Deleted successfully
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isSuccess` | boolean | Yes |  |
| `cause` | string \| null | No |  |
| `replaySettings` | object \| null | No |  |
| `replaySettings.id` | string | Yes | Stable identifier (UUID) for this replay configuration. |
| `replaySettings.name` | string | Yes | Human-readable label for this replay configuration. Shown in the dashboard. May be empty. On PATCH, `null` leaves it unchanged. |
| `replaySettings.status` | string | Yes | Whether session replay capture is currently active. Set to "Enabled" to start capturing replays from whitelisted domains, or "Disabled" to pause capture without losing the configuration. On PATCH, `null` leaves it unchanged. One of: `"Disabled"`, `"Enabled"`. |
| `replaySettings.createdAt` | string | Yes | ISO-8601 timestamp when this configuration was created. |
| `replaySettings.updatedAt` | string \| null | No | ISO-8601 timestamp of the most recent update, or null if never updated. |
| `replaySettings.whitelistDomains` | string[] \| null | No | Bare hostnames (e.g. `example.com`) where session replay capture is permitted. Replays initiated from any host not in this list are dropped. PATCH replaces the list; partial updates are not merged. On PATCH, `null` leaves it unchanged. |
| `replaySettings.customDomain` | string \| null | No | Optional custom domain (CNAME) for hosting the replay capture script. Leave null to use the default Ours Privacy domain. |
| `replaySettings.pixel` | string | Yes | Server-assigned public replay token used by the browser SDK to start session replay capture. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).
