# Web Scanner Rules

> Manage suppression rules attached to a web scanner. Rules tell the scanner to ignore specific cookies, hostnames, or full script URLs during crawl analysis. Scoped to a parent scanner: list, find, create, update, or delete by rule id.

Source: https://docs.oursprivacy.com/docs/platform-api/web-scanner-rules

Manage suppression rules attached to a web scanner. Rules tell the scanner to ignore specific cookies, hostnames, or full script URLs during crawl analysis. Rules are scoped to a parent scanner: list, find, create, update, or delete by rule id.

## GET /rest/v1/web-scanner-rules

List suppression rules for a single web scanner. Requires the `scannerId` query parameter — rules are always scoped to a parent scanner. Not paginated; the per-scanner rule count is bounded. Requires API-key scope or current OAuth user permission: webScanner:find

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-scanner-rules`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `scannerId` | query | string | Yes | The web scanner whose suppression rules should be returned. |

### Responses

- `200`: List of suppression rules for the requested scanner
- `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 |  |
| `entities[].scannerId` | string | Yes |  |
| `entities[].accountId` | string | Yes |  |
| `entities[].name` | string | Yes |  |
| `entities[].reason` | string \| null | No | One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `entities[].notes` | string \| null | No |  |
| `entities[].priority` | integer | Yes |  |
| `entities[].cookiePatterns` | string[] | Yes |  |
| `entities[].domainPatterns` | string[] | Yes |  |
| `entities[].scriptPatterns` | string[] | Yes |  |
| `entities[].createdAt` | string | Yes |  |
| `entities[].updatedAt` | string \| null | No |  |
| `entities[].createdByUserId` | string \| null | No |  |
| `entities[].updatedByUserId` | string \| null | No |  |

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

## POST /rest/v1/web-scanner-rules

Create a suppression rule on a web scanner. Auth is enforced against the parent scanner via `webScanner:update`. At least one of `cookiePatterns`, `domainPatterns`, or `scriptPatterns` should be set for the rule to match anything; omitted pattern arrays default to `[]`. Requires API-key scope or current OAuth user permission: webScanner:update

Request URL: `POST https://app.oursprivacy.com/rest/v1/web-scanner-rules`

Authentication: apiKey or oauth2.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scannerId` | string | Yes | The web scanner this rule belongs to. |
| `name` | string | Yes | User-friendly name for the suppression rule. |
| `priority` | integer | Yes | Rule priority (1–10,000). Lower numbers are evaluated first when multiple rules match. |
| `reason` | string \| null | No | Why this rule was added. Surfaced in audit views. Send `null` to clear an existing reason on patch. One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `notes` | string \| null | No | Free-form notes about why this rule exists or what it covers. Trimmed server-side; empty strings become `null`. |
| `cookiePatterns` | string[] | No | Glob patterns matched against cookie names (e.g. `_ga*`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |
| `domainPatterns` | string[] | No | Glob patterns matched against cookie domain / script hostname (e.g. `*.google-analytics.com`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |
| `scriptPatterns` | string[] | No | Glob patterns matched against full script URLs (e.g. `https://www.googletagmanager.com/gtm.js?id=*`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |

### Responses

- `200`: Created suppression rule
- `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 |  |
| `scannerId` | string | Yes |  |
| `accountId` | string | Yes |  |
| `name` | string | Yes |  |
| `reason` | string \| null | No | One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `notes` | string \| null | No |  |
| `priority` | integer | Yes |  |
| `cookiePatterns` | string[] | Yes |  |
| `domainPatterns` | string[] | Yes |  |
| `scriptPatterns` | string[] | Yes |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string \| null | No |  |
| `createdByUserId` | string \| null | No |  |
| `updatedByUserId` | string \| null | No |  |

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

## GET /rest/v1/web-scanner-rules/{id}

Find a single web scanner rule by ID. Requires API-key scope or current OAuth user permission: webScanner:find

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-scanner-rules/{id}`

Authentication: apiKey or oauth2.

### Parameters

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

### Responses

- `200`: Suppression rule 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 |  |
| `scannerId` | string | Yes |  |
| `accountId` | string | Yes |  |
| `name` | string | Yes |  |
| `reason` | string \| null | No | One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `notes` | string \| null | No |  |
| `priority` | integer | Yes |  |
| `cookiePatterns` | string[] | Yes |  |
| `domainPatterns` | string[] | Yes |  |
| `scriptPatterns` | string[] | Yes |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string \| null | No |  |
| `createdByUserId` | string \| null | No |  |
| `updatedByUserId` | string \| null | No |  |

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

## PATCH /rest/v1/web-scanner-rules/{id}

Partially update a suppression rule. Only the fields you send are changed. List-valued fields (`cookiePatterns`, `domainPatterns`, `scriptPatterns`) are replaced wholesale when sent. Requires API-key scope or current OAuth user permission: webScanner:update

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/web-scanner-rules/{id}`

Authentication: apiKey or oauth2.

### Parameters

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No |  |
| `priority` | integer | No |  |
| `reason` | string \| null | No | Why this rule was added. Surfaced in audit views. Send `null` to clear an existing reason on patch. One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `notes` | string \| null | No | Free-form notes about why this rule exists or what it covers. Trimmed server-side; empty strings become `null`. |
| `cookiePatterns` | string[] | No | Glob patterns matched against cookie names (e.g. `_ga*`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |
| `domainPatterns` | string[] | No | Glob patterns matched against cookie domain / script hostname (e.g. `*.google-analytics.com`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |
| `scriptPatterns` | string[] | No | Glob patterns matched against full script URLs (e.g. `https://www.googletagmanager.com/gtm.js?id=*`). Max 100 entries. When sent on PATCH, replaces the existing list wholesale. |

### Responses

- `200`: Updated suppression rule
- `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 |  |
| `scannerId` | string | Yes |  |
| `accountId` | string | Yes |  |
| `name` | string | Yes |  |
| `reason` | string \| null | No | One of: `"approved"`, `"baa"`, `"compliant"`, `"firstParty"`, `"ignore"`, `"internal"`, `"other"`, `null`. |
| `notes` | string \| null | No |  |
| `priority` | integer | Yes |  |
| `cookiePatterns` | string[] | Yes |  |
| `domainPatterns` | string[] | Yes |  |
| `scriptPatterns` | string[] | Yes |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string \| null | No |  |
| `createdByUserId` | string \| null | No |  |
| `updatedByUserId` | string \| null | No |  |

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

## DELETE /rest/v1/web-scanner-rules/{id}

Delete a web scanner rule. Requires API-key scope or current OAuth user permission: webScanner:update

Request URL: `DELETE https://app.oursprivacy.com/rest/v1/web-scanner-rules/{id}`

Authentication: apiKey or oauth2.

### Parameters

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

### 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 |
| --- | --- | --- | --- |
| `id` | string | Yes | The id of the suppression rule that was deleted. |
| `deleted` | boolean | Yes | True when the rule was deleted. |

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