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

status?string

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"          }        ]      }    ]  }}

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`