Web Scanners API - Ours Privacy

Manage web scanners that crawl your sites for trackers, cookies, and third-party requests. Create a scanner against a root domain, edit its crawl scope, trigger a scan on demand, or delete it (which also removes its suppression rules).

GET/rest/v1/web-scanners

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners"

{  "entities": [    {      "id": "string",      "accountId": "string",      "name": "string",      "status": "Disabled",      "rootDomain": "string",      "excludedPatterns": [        "string"      ],      "includedUrls": [        "string"      ],      "urlLimit": 0,      "scanSchedule": "daily",      "nextScheduledScanAt": "string",      "scanStatus": "idle",      "lastScannedAt": "string",      "lastScanStartedAt": "string",      "lastRunCookieCount": 0,      "lastRunRequestCount": 0,      "lastRunSuccessUrlCount": 0,      "lastRunHighRiskRequestCount": 0,      "createdAt": "string",      "updatedAt": "string"    }  ]}

POST/rest/v1/web-scanners

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

rootDomain*string

Root domain to crawl (e.g. example.com). Required on create. Missing or empty values fail request validation as HTTP 400. Present-but-malformed values are rejected as HTTP 400 with the validation reason in details.

Length1 <= length

name?|

Optional display name for this web scanner.

status?string

Whether this web scanner is enabled. Defaults to Enabled.

Value in

"Disabled"
"Enabled"

excludedPatterns?array<string>|

URL glob patterns to skip during crawl. Max 100 entries.

includedUrls?array<string>|

Additional seed URLs to include as crawl entry points. Each must be an http(s) URL. Max 100 entries.

urlLimit?|

Maximum URLs to crawl per scan (1–20,000). Defaults to 100 when omitted.

scanSchedule?string

How often the scanner crawls this monitor on its own: daily, weekly, monthly, or manual to disable scheduled crawls and only run on demand. Defaults to weekly. Cadences advance on UTC calendar days from the last completed scan.

Value in

"daily"
"manual"
"monthly"
"weekly"

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/web-scanners" \  -H "Content-Type: application/json" \  -d '{    "rootDomain": "string"  }'

{  "id": "string",  "accountId": "string",  "name": "string",  "status": "Disabled",  "rootDomain": "string",  "excludedPatterns": [    "string"  ],  "includedUrls": [    "string"  ],  "urlLimit": 0,  "scanSchedule": "daily",  "nextScheduledScanAt": "string",  "scanStatus": "idle",  "lastScannedAt": "string",  "lastScanStartedAt": "string",  "lastRunCookieCount": 0,  "lastRunRequestCount": 0,  "lastRunSuccessUrlCount": 0,  "lastRunHighRiskRequestCount": 0,  "createdAt": "string",  "updatedAt": "string"}

GET/rest/v1/web-scanners/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string"

{  "id": "string",  "accountId": "string",  "name": "string",  "status": "Disabled",  "rootDomain": "string",  "excludedPatterns": [    "string"  ],  "includedUrls": [    "string"  ],  "urlLimit": 0,  "scanSchedule": "daily",  "nextScheduledScanAt": "string",  "scanStatus": "idle",  "lastScannedAt": "string",  "lastScanStartedAt": "string",  "lastRunCookieCount": 0,  "lastRunRequestCount": 0,  "lastRunSuccessUrlCount": 0,  "lastRunHighRiskRequestCount": 0,  "createdAt": "string",  "updatedAt": "string"}

PATCH/rest/v1/web-scanners/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

rootDomain?|

Replace the scanner root domain. When provided, malformed values are rejected as HTTP 400 with the validation reason in details.

name?string|null

status?string

Value in

"Disabled"
"Enabled"

excludedPatterns?array<string>|null

includedUrls?array<string>|null

urlLimit?number|null

scanSchedule?string

Value in

"daily"
"manual"
"monthly"
"weekly"

Response Body

`application/json`

curl -X PATCH "https://example.com/rest/v1/web-scanners/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "accountId": "string",  "name": "string",  "status": "Disabled",  "rootDomain": "string",  "excludedPatterns": [    "string"  ],  "includedUrls": [    "string"  ],  "urlLimit": 0,  "scanSchedule": "daily",  "nextScheduledScanAt": "string",  "scanStatus": "idle",  "lastScannedAt": "string",  "lastScanStartedAt": "string",  "lastRunCookieCount": 0,  "lastRunRequestCount": 0,  "lastRunSuccessUrlCount": 0,  "lastRunHighRiskRequestCount": 0,  "createdAt": "string",  "updatedAt": "string"}

DELETE/rest/v1/web-scanners/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/rest/v1/web-scanners/string"

{  "id": "string",  "deleted": true}

POST/rest/v1/web-scanners/{id}/trigger

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/web-scanners/string/trigger"

{  "id": "string",  "accountId": "string",  "name": "string",  "status": "Disabled",  "rootDomain": "string",  "excludedPatterns": [    "string"  ],  "includedUrls": [    "string"  ],  "urlLimit": 0,  "scanSchedule": "daily",  "nextScheduledScanAt": "string",  "scanStatus": "idle",  "lastScannedAt": "string",  "lastScanStartedAt": "string",  "lastRunCookieCount": 0,  "lastRunRequestCount": 0,  "lastRunSuccessUrlCount": 0,  "lastRunHighRiskRequestCount": 0,  "createdAt": "string",  "updatedAt": "string"}

POST/rest/v1/web-scanners/{id}/authenticated-scan

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expiresInHours*integer

Whole-hour validity window for these credentials. Send a fresh credential for every externally scheduled scan.

Range1 <= value <= 24

credentials*array<>

Short-lived credentials for this scan. Their values are not returned in API responses or captured in scan results.

Items1 <= items <= 10

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/web-scanners/string/authenticated-scan" \  -H "Content-Type: application/json" \  -d '{    "expiresInHours": 2,    "credentials": [      {        "location": "header",        "name": "Authorization",        "value": "Bearer YOUR_TOKEN"      }    ]  }'

{  "id": "string",  "accountId": "string",  "name": "string",  "status": "Disabled",  "rootDomain": "string",  "excludedPatterns": [    "string"  ],  "includedUrls": [    "string"  ],  "urlLimit": 0,  "scanSchedule": "daily",  "nextScheduledScanAt": "string",  "scanStatus": "idle",  "lastScannedAt": "string",  "lastScanStartedAt": "string",  "lastRunCookieCount": 0,  "lastRunRequestCount": 0,  "lastRunSuccessUrlCount": 0,  "lastRunHighRiskRequestCount": 0,  "createdAt": "string",  "updatedAt": "string"}

POST/rest/v1/web-scanners/{id}/targeted-scan

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

targetUrl*string

Exact in-scope HTTP(S) page URL to verify. Fragments are removed; query parameters are retained.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/web-scanners/string/targeted-scan" \  -H "Content-Type: application/json" \  -d '{    "targetUrl": "https://example.com/privacy"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "scannerId": "4d4dc154-bef0-4571-8fa5-b883608b16c1",  "requestedUrl": "http://example.com",  "resolvedUrl": "string",  "status": "queued",  "cause": "string",  "createdAt": "string",  "completedAt": "string",  "run": {    "metadata": {      "success_urls": [        "string"      ],      "failed_urls": [        {          "url": "string",          "status_code": 0,          "details": "string"        }      ],      "excluded_urls": [        "string"      ],      "excluded_patterns": [        "string"      ]    },    "summary_generated_at": "string",    "cookieCount": 0,    "localStorageCount": 0,    "requestCount": 0,    "vendorCount": 0  }}

GET/rest/v1/web-scanners/{id}/verification-run

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

runId*string

Verification run UUID returned by the targeted scan command.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/verification-run?runId=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "scannerId": "4d4dc154-bef0-4571-8fa5-b883608b16c1",  "requestedUrl": "http://example.com",  "resolvedUrl": "string",  "status": "queued",  "cause": "string",  "createdAt": "string",  "completedAt": "string",  "run": {    "metadata": {      "success_urls": [        "string"      ],      "failed_urls": [        {          "url": "string",          "status_code": 0,          "details": "string"        }      ],      "excluded_urls": [        "string"      ],      "excluded_patterns": [        "string"      ]    },    "summary_generated_at": "string",    "cookieCount": 0,    "localStorageCount": 0,    "requestCount": 0,    "vendorCount": 0  }}

GET/rest/v1/web-scanners/{id}/verification-runs

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

limit?integer

How many runs to read, newest first. Defaults to 20, capped at 50.

Range1 <= value <= 50

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/verification-runs"

{  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "scannerId": "4d4dc154-bef0-4571-8fa5-b883608b16c1",      "requestedUrl": "http://example.com",      "resolvedUrl": "string",      "status": "queued",      "cause": "string",      "createdAt": "string",      "completedAt": "string",      "run": {        "metadata": {          "success_urls": [            "string"          ],          "failed_urls": [            {              "url": "string",              "status_code": 0,              "details": "string"            }          ],          "excluded_urls": [            "string"          ],          "excluded_patterns": [            "string"          ]        },        "summary_generated_at": "string",        "cookieCount": 0,        "localStorageCount": 0,        "requestCount": 0,        "vendorCount": 0      }    }  ]}

GET/rest/v1/web-scanners/{id}/findings

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

date?string

Which scan run to read, as an ISO-8601 timestamp. Only the UTC calendar day is used to select the run; the time component is ignored. Defaults to the most recent run when omitted.

Formatdate-time

limit?integer

Maximum number of findings to return. Defaults to 25; clamped to 1–100.

Range1 <= value <= 100

offset?|

Skip this many findings before returning. Use with limit for load-more paging.

Range0 <= value

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/findings"

{  "items": [    {      "hostname": "string",      "urls": [        "string"      ],      "types": [        "audio"      ],      "cookies": [        {          "name": "string",          "value": "string",          "domain": "string",          "path": "string"        }      ],      "seenOn": [        "string"      ],      "privacyKeywords": [        "string"      ],      "risk": "string",      "category": "string",      "displayName": "string",      "dataFlow": {        "recipient": {          "hostname": "string",          "displayName": "string",          "category": "string",          "risk": "string"        },        "categories": [          "credit_card"        ],        "signals": [          {            "category": "credit_card",            "source": "query_parameter",            "field": "string",            "encoding": "string"          }        ],        "requestCount": 0      },      "coveredByCmp": true,      "coveredByVendorLabel": "string"    }  ],  "total": 0,  "hasMore": true}

GET/rest/v1/web-scanners/{id}/cookies

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

date?string

Which scan run to read, as an ISO-8601 timestamp. Only the UTC calendar day is used to select the run; the time component is ignored. Defaults to the most recent run when omitted.

Formatdate-time

limit?integer

Maximum number of findings to return. Defaults to 25; clamped to 1–100.

Range1 <= value <= 100

offset?|

Skip this many findings before returning. Use with limit for load-more paging.

Range0 <= value

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/cookies"

{  "cookies": [    {      "name": "string",      "value": "string",      "domain": "string",      "path": "string"    }  ],  "localStorage": [    {      "name": "string",      "value": "string"    }  ],  "totalCookies": 0,  "totalLocalStorage": 0,  "hasMore": true}

GET/rest/v1/web-scanners/{id}/summary

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

date?string

Which scan run to read, as an ISO-8601 timestamp. Only the UTC calendar day is used to select the run; the time component is ignored. Defaults to the most recent run when omitted.

Formatdate-time

runRevision?string

coverageRevision?string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/summary"

{  "scannerId": "string",  "rootDomain": "string",  "scanStatus": "idle",  "runDate": "string",  "runRevision": "string",  "coverageRevision": "string",  "hostCount": 0,  "vendorCount": 0,  "cookieCount": 0,  "localStorageCount": 0,  "privacyPolicyCount": 0,  "privacyPolicies": [    {      "url": "http://example.com",      "hostnames": [        "string"      ],      "text": "string"    }  ],  "privacyPolicyHosts": [    {      "hostname": "string",      "privacyPolicyUrl": "string"    }  ],  "countsByRisk": {    "high": 0,    "medium": 0,    "low": 0,    "unknown": 0  },  "byCategory": [    {      "category": "string",      "hostCount": 0    }  ],  "coverage": {    "totalHostCount": 0,    "coveredHostCount": 0,    "needsDecisionHostCount": 0,    "coveragePercent": 0  },  "delta": {    "newHostCount": 0,    "removedHostCount": 0  },  "topUncoveredHosts": [    {      "hostname": "string",      "urls": [        "string"      ],      "types": [        "audio"      ],      "cookies": [        {          "name": "string",          "value": "string",          "domain": "string",          "path": "string"        }      ],      "seenOn": [        "string"      ],      "privacyKeywords": [        "string"      ],      "risk": "string",      "category": "string",      "displayName": "string",      "dataFlow": {        "recipient": {          "hostname": "string",          "displayName": "string",          "category": "string",          "risk": "string"        },        "categories": [          "credit_card"        ],        "signals": [          {            "category": "credit_card",            "source": "query_parameter",            "field": "string",            "encoding": "string"          }        ],        "requestCount": 0      },      "coveredByCmp": true,      "coveredByVendorLabel": "string"    }  ],  "accessibility": {    "engine": "string",    "score": 0,    "pagesEvaluated": 0,    "totalViolations": 0,    "totalNodes": 0,    "countsByImpact": {      "critical": 0,      "serious": 0,      "moderate": 0,      "minor": 0    },    "topViolations": [      {        "id": "string",        "impact": "string",        "help": "string",        "helpUrl": "string",        "wcagTags": [          "string"        ],        "pageCount": 0,        "nodeCount": 0,        "pages": [          "string"        ],        "sampleNodes": [          {            "target": [              "string"            ],            "html": "string",            "failureSummary": "string"          }        ]      }    ]  }}

GET/rest/v1/web-scanners/{id}/decision-queue

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

limit?|

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?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

date?string

Which scan run to read, as an ISO-8601 timestamp. Only the UTC calendar day is used to select the run; the time component is ignored. Defaults to the most recent run when omitted.

Formatdate-time

runRevision?string

coverageRevision?string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/web-scanners/string/decision-queue"

{  "scannerId": "string",  "runDate": "string",  "runRevision": "string",  "coverageRevision": "string",  "total": 0,  "entities": [    {      "hostname": "string",      "displayName": "string",      "risk": "string",      "category": "string",      "seenOn": [        "string"      ],      "dataFlow": {        "recipient": {          "hostname": "string",          "displayName": "string",          "category": "string",          "risk": "string"        },        "categories": [          "credit_card"        ],        "signals": [          {            "category": "credit_card",            "source": "query_parameter",            "field": "string",            "encoding": "string"          }        ],        "requestCount": 0      }    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}

POST/rest/v1/web-scanners/{id}/resolve-coverage-gap

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

runDate*string

Formatdate-time

runRevision*string

Length1 <= length

coverageRevision*string

Length1 <= length

hostname*string

Length1 <= length <= 253

idempotencyKey*string

Formatuuid

suppression*

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/web-scanners/string/resolve-coverage-gap" \  -H "Content-Type: application/json" \  -d '{    "runDate": "2019-08-24T14:15:22Z",    "runRevision": "string",    "coverageRevision": "string",    "hostname": "string",    "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1",    "suppression": {      "reason": "ignore"    }  }'

{  "status": "already_resolved",  "hostname": "string",  "effectState": "preexisting_coverage",  "coverageSource": "cmp",  "suppressionRuleId": "string",  "coveredByVendorLabel": "string",  "committedCoverageRevision": "string"}

Web Scanners

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`