Scanning API

Cookie scanning detects all cookies set by your website. Use it to keep your cookie inventory up to date.

Triggering Scans

POST /api/v1/sites/:siteId/scan Start a new scan

Triggers an asynchronous cookie scan. The scanner visits your site in a headless browser and records all cookies. Returns 409 if a scan is already in progress. Returns 202 (accepted) on success.

Response

{
"scan": {
  "id": "01HXYZ...",
  "status": "pending",
  "siteId": "01HABC..."
}
}

GET /api/v1/sites/:siteId/scans List scan history

Returns up to 20 recent scans, newest first. Each scan includes newCookies and removedCookies counts computed by comparing against the previous scan.

Response

{
"scans": [
  {
    "id": "01HXYZ...",
    "site_id": "01HABC...",
    "status": "completed",
    "cookies_found": 12,
    "started_at": "2026-02-14T02:00:00Z",
    "completed_at": "2026-02-14T02:00:15Z",
    "newCookies": 2,
    "removedCookies": 1
  },
  {
    "id": "01HPREV...",
    "status": "completed",
    "cookies_found": 11,
    "started_at": "2026-02-07T02:00:00Z",
    "completed_at": "2026-02-07T02:00:12Z",
    "newCookies": 0,
    "removedCookies": 0
  }
]
}

Scan Diffs

GET /api/v1/sites/:siteId/scans/:scanId/diff Get cookie diff for a scan

Compares a scan’s cookie snapshot against the previous completed scan. Shows exactly which cookies were added, removed, or unchanged.

Response

{
"scanId": "01HXYZ...",
"previousScanId": "01HPREV...",
"added": [
  { "name": "_fbp", "domain": ".facebook.com" },
  { "name": "hubspotutk", "domain": ".hubspot.com" }
],
"removed": [
  { "name": "_old_tracker", "domain": ".example.com" }
],
"unchanged": 10
}

Scan Schedule

GET /api/v1/sites/:siteId/scan/schedule Get scan schedule

Returns the current scan schedule. nextScanAt is computed based on frequency and preferred time.

Response

{
"scanFrequency": "weekly",
"scanPreferredHour": 2,
"scanPreferredDay": 1,
"lastScanAt": "2026-02-14T02:00:00Z",
"nextScanAt": "2026-02-21T02:00:00Z"
}

PUT /api/v1/sites/:siteId/scan/schedule Update scan schedule

Updates the automated scan schedule.

scanFrequency: manual, daily, weekly, or monthly

scanPreferredHour: 0-23 (UTC hour)

scanPreferredDay: For weekly: 0-6 (0=Sunday). For monthly: 1-28 (day of month).

Request Body

{
"scanFrequency": "weekly",
"scanPreferredHour": 3,
"scanPreferredDay": 1
}

Response

{
"success": true
}

Automated scans

When a schedule is set, CookieBoss automatically runs scans at the configured time. Results appear in scan history and new cookies are flagged in the Cookie Inventory.