> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Visual Monitoring API

Screenshot-based visual regression detection. This page lists all 9 endpoints in the Visual Monitoring area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [Capture sub-page screenshot](#capture-sub-page): `POST /api/monitors/{id}/sub-pages/{subPageId}/capture`
- [Get sub-page visual data](#get-sub-page-visual): `GET /api/monitors/{id}/sub-pages/{subPageId}/visual`
- [Get visual monitoring data](#get-visual-data): `GET /api/monitors/{id}/visual`
- [Capture screenshot](#capture-screenshot): `POST /api/monitors/{id}/visual/capture`
- [Set visual baseline](#set-visual-baseline): `POST /api/monitors/{id}/visual/baseline`
- [Compare visual snapshots](#compare-visual): `POST /api/monitors/{id}/visual/compare`
- [Get deletable snapshots](#get-deletable-snapshots): `GET /api/monitors/{id}/visual/delete`
- [Delete visual snapshots (POST)](#delete-visual-snapshots-post): `POST /api/monitors/{id}/visual/delete`
- [Delete visual snapshots](#delete-visual-snapshots): `DELETE /api/monitors/{id}/visual/delete`

## Capture sub-page screenshot

`POST /api/monitors/{id}/sub-pages/{subPageId}/capture`

Queue a screenshot of a sub-page now. Refused with 409 `VISUAL_DISABLED` while the monitor's visual checks are off, 403 `LIMIT_EXCEEDED` when the monitor is not within the plan's visual monitor limit (or visual checks are off and the limit is reached), 409 `SUBPAGE_NOT_ON_PLAN` for a page beyond the plan's page limit, and 409 `VISUAL_TARGET_NOT_READY` when the page's capture target is not set up yet.

**Parameters**

- `id` (path, string (uuid), required)
- `subPageId` (path, string (uuid), required)

**Responses**

- `200`: Screenshot captured.
- `403`: `LIMIT_EXCEEDED` (`feature: maxVisualMonitors`) or `FEATURE_RESTRICTED`.
- `409`: Not captured: `VISUAL_DISABLED`, `SUBPAGE_NOT_ON_PLAN`, `VISUAL_TARGET_NOT_READY`, or the site is down right now (`siteDown: true`).

## Get sub-page visual data

`GET /api/monitors/{id}/sub-pages/{subPageId}/visual`

Get visual monitoring data for a specific sub-page.

**Parameters**

- `id` (path, string (uuid), required)
- `subPageId` (path, string (uuid), required)

**Responses**

- `200`: Sub-page visual data.

## Get visual monitoring data

`GET /api/monitors/{id}/visual`

Get visual monitoring history and screenshots.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Visual monitoring data. Body: [VisualDataResponse](https://docs.visualsentinel.com/reference/models/visual-data-response.md).

## Capture screenshot

`POST /api/monitors/{id}/visual/capture`

Capture a new screenshot for visual comparison. Only for a monitor with visual checks on and within the plan's visual monitor limit, the same rules as the scheduled captures. A monitor with visual checks off is refused with 409 `VISUAL_DISABLED`, or with 403 `LIMIT_EXCEEDED` when the workspace is also at its visual monitor limit (visual checks could not be turned on). A monitor past the limit after a plan change is refused with 403 `LIMIT_EXCEEDED`.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Screenshot captured. Body: object.
- `403`: Plan restriction: `LIMIT_EXCEEDED` (`feature: maxVisualMonitors`, the workspace is at or over its visual monitor limit) or `FEATURE_RESTRICTED` (the plan has no visual checks).
- `409`: Not captured: `VISUAL_DISABLED` (visual checks are off for this monitor; turn them on first), or the site is down right now (`siteDown: true`).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | No |   |
| `screenshotUrl` | string | No |   |

## Set visual baseline

`POST /api/monitors/{id}/visual/baseline`

Set the current screenshot as the baseline for visual comparisons.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Baseline set.

## Compare visual snapshots

`POST /api/monitors/{id}/visual/compare`

Compare two visual snapshots and return diff percentage.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Comparison result with diff percentage.

## Get deletable snapshots

`GET /api/monitors/{id}/visual/delete`

List visual snapshots that can be deleted.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: List of deletable snapshots.

## Delete visual snapshots (POST)

`POST /api/monitors/{id}/visual/delete`

Delete specific visual snapshots by IDs.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Snapshots deleted.

## Delete visual snapshots

`DELETE /api/monitors/{id}/visual/delete`

Delete visual monitoring data.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Snapshots deleted.

## Data models

Request and response shapes these endpoints use: [VisualDataResponse](https://docs.visualsentinel.com/reference/models/visual-data-response.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.