Scanner

The scanner crawls your site to detect third-party tracking scripts and cookies. Detected services are matched against a known library and can be automatically configured as services with their correct cookie categories.

Scan and configure in 3 steps: Trigger a scan → poll for completion → auto-create services. This is the fastest way to set up consent for a new site.

POST

Trigger a scan

POST /sites/{id}/scan

Triggers a new cookie/script scan for a site. Optionally provide a specific URL to scan instead of the site's homepage.

Path parameters

idstringrequired

Site ID (UUID)

Request body

urlstring

Specific URL to scan. Defaults to the site's homepage if omitted.

Response fields

Field	Type	Description
`id`	string	Scan ID (UUID)
`siteId`	string	Parent site ID
`url`	string	The URL that was scanned
`status`	string	Scan status: `pending`, `running`, `completed`, or `failed`
`detectedServices`	array\|null	Services found (populated when completed)
`unrecognizedScripts`	array\|null	Unknown scripts for manual review
`errorMessage`	string\|null	Error details if scan failed
`createdAt`	string	ISO 8601 timestamp

curl -X POST https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/scan \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing"}'

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/scan`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'https://example.com/pricing' }),
  },
);
const scan = await res.json();

import requests

res = requests.post(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/scan",
    headers={
        "Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7",
        "Content-Type": "application/json",
    },
    json={"url": "https://example.com/pricing"},
)
scan = res.json()

Response 201

{
  "id": "s1c2a3n4-d5e6-7f89-0a1b-2c3d4e5f6789",
  "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
  "url": "https://example.com/pricing",
  "status": "pending",
  "detectedServices": null,
  "unrecognizedScripts": null,
  "errorMessage": null,
  "createdAt": "2025-03-20T14:22:00.000Z"
}

GET

List scans

GET /sites/{id}/scans

Returns all scan results for a site, ordered by most recent first.

Path parameters

idstringrequired

Site ID (UUID)

curl https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/scans \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/scans`,
  { headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' } },
);
const scans = await res.json();

import requests

res = requests.get(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/scans",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
scans = res.json()

Response 200

[
  {
    "id": "s1c2a3n4-d5e6-7f89-0a1b-2c3d4e5f6789",
    "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
    "url": "https://example.com",
    "status": "completed",
    "detectedServices": [
      { "name": "Google Analytics", "category": "statistics" },
      { "name": "Facebook Pixel", "category": "marketing" }
    ],
    "unrecognizedScripts": [
      { "src": "https://cdn.example.com/tracker.js" }
    ],
    "errorMessage": null,
    "createdAt": "2025-03-20T14:22:00.000Z"
  }
]

GET

Get a scan result

GET /sites/{id}/scans/{scanId}

Returns a single scan result by its ID. Use this to poll for completion after triggering a scan.

Path parameters

idstringrequired

Site ID (UUID)

scanIdstringrequired

Scan ID (UUID)

Error responses

Status	Description
`404`	Scan not found

curl https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/scans/s1c2a3n4-d5e6-7f89-0a1b-2c3d4e5f6789 \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/scans/${scanId}`,
  { headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' } },
);
const scan = await res.json();

import requests

res = requests.get(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/scans/{scan_id}",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
scan = res.json()

Response 200

Returns the full scan object (same shape as list items).

POST

Configure services from scan

POST /sites/{id}/scans/{scanId}/configure

Automatically creates services and cookies based on a completed scan's detected services. This is the fastest way to set up consent after scanning.

Path parameters

idstringrequired

Site ID (UUID)

scanIdstringrequired

Scan ID (UUID). The scan must have status completed.

Response fields

Field	Type	Description
`created`	integer	Number of services created
`services`	array	The service objects that were created

Error responses

Status	Description
`400`	Scan is not completed yet
`404`	Scan not found

curl -X POST https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/scans/s1c2a3n4-d5e6-7f89-0a1b-2c3d4e5f6789/configure \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/scans/${scanId}/configure`,
  {
    method: 'POST',
    headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' },
  },
);
const result = await res.json();

import requests

res = requests.post(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/scans/{scan_id}/configure",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
result = res.json()

Response 200

{
  "created": 2,
  "services": [
    {
      "id": "svc-1234-abcd",
      "slug": "google-analytics",
      "label": "Google Analytics",
      "categoryId": "d2e3f4a5-b6c7-8901-def0-234567890123"
    },
    {
      "id": "svc-5678-efgh",
      "slug": "facebook-pixel",
      "label": "Facebook Pixel",
      "categoryId": "e3f4a5b6-c7d8-9012-ef01-345678901234"
    }
  ]
}