Name: Lumen GDPR Website Scanner API: cookies and trackers
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-lumen
Availability: InStock
Author: API Market

# Lumen GDPR Website Scanner API

## Overview

The Lumen GDPR API loads a web page in a real browser and reports what it does before anyone clicks "Accept". It returns the cookies, trackers, fonts and forms that break GDPR and ePrivacy rules, and every finding comes with evidence, a fix and the article it rests on.

It is built for agencies, developers, DPOs and consent platforms that answer for a website. Findings are automated technical signals, not legal advice.

## Features

*   **Four endpoints**: a scan (`POST` or `GET`), the rule catalogue and a health check.
*   **A real browser**: full mode runs Chromium with a fresh profile per scan, so it catches what JavaScript and tag managers do before consent.
*   **Quick mode**: plain HTTP in under a second, for frequent checks of headers, forms, fonts and the privacy policy.
*   **26 rules with their legal basis**: each finding has a stable id, a severity, evidence, a recommendation and the GDPR or ePrivacy article or ruling behind it.
*   **Consent platforms**: detects 25 CMPs (OneTrust, Cookiebot, Didomi, Usercentrics and more), the banner and the IAB TCF API.
*   **Privacy policy check**: finds the policy, reads it and checks the items GDPR art. 13 requires.
*   **Score and grade**: a score from 0 to 100 and a grade from `A` to `F` summarise every scan.
*   **Hosted in the EU**: runs in Paris, with no request logs of the URLs you scan.
*   **Rate limit**: 1 request per second on every plan.

## Use Cases

*   **Agencies and freelancers**: scan every client site after a release or a new tag, and send a report that cites the article behind each issue.
*   **CI gates**: fail a deploy when a `high` finding appears, such as a new pixel firing before consent or a form over HTTP.
*   **Compliance and DPOs**: monitor a portfolio of sites weekly, with a score and grade you can track over time.
*   **Consent platforms and plugins**: show customers what their site still does before consent, inside your product.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/hybrid-forge-lab/lumen
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key. Call the API from your server and set a client timeout of about 60 seconds for full scans of heavy pages.

### Endpoints

#### 1. Health check

Returns `ok`, the service version and its uptime.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/lumen/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.4.0",
  "uptime_s": 0
}
```

#### 2. Scan a page (POST)

Loads the page and returns a full report: findings, cookies, browser storage, third parties, consent platform, Google Fonts, forms, security headers and the privacy policy check. The example is a full scan of `example.com`.

**Method:** `POST`

**Endpoint:** `/v1/scan`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | body | A page (`https://www.example.pt/shop`) or a domain (`example.pt`). IP addresses and ports other than 80 and 443 are rejected. | string | Yes | - | - |
| `mode` | body | `full`: real Chromium, catches JavaScript cookies and trackers. `quick`: plain HTTP, sees `Set-Cookie` headers and resources in the HTML only. | string | No | `full` | - |
| `include_policy` | body | Fetch the privacy policy linked from the page and check its GDPR art. 13 items. | boolean | No | `true` | - |
| `fresh` | body | Skip the 1-hour cache and scan again, for example after a fix. It still counts towards the per-site limit. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/lumen/v1/scan' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "mode": "full", "include_policy": true}'
```

**Example Response (200 OK):**

```json
{
  "scan_status": "ok",
  "unavailable_reason": null,
  "url": "https://example.com",
  "final_url": "https://example.com/",
  "mode": "full",
  "status": 200,
  "scanned_at": "2026-10-31T00:30:03+00:00",
  "score": 77,
  "grade": "B",
  "summary": {
    "high": 1,
    "medium": 0,
    "low": 1,
    "info": 0
  },
  "findings": [
    {
      "id": "LUM-05",
      "severity": "high",
      "title": "No privacy policy link found",
      "detail": "No link to a privacy policy was found on the page.",
      "evidence": {},
      "recommendation": "Link the privacy policy from every page (usually in the footer) and from every form that collects personal data.",
      "legal_basis": "GDPR art. 12, 13"
    },
    {
      "id": "LUM-11",
      "severity": "low",
      "title": "HSTS header missing",
      "detail": "Without Strict-Transport-Security, a first visit can be downgraded to HTTP.",
      "evidence": {},
      "recommendation": "Send Strict-Transport-Security: max-age=31536000; includeSubDomains.",
      "legal_basis": "GDPR art. 32"
    }
  ],
  "cookies": [],
  "storage": [],
  "third_parties": [],
  "consent": {
    "cmp": null,
    "banner_detected": false,
    "tcf_api": false
  },
  "google_fonts": false,
  "forms": [],
  "security": {
    "https": true,
    "hsts": false,
    "csp": false,
    "referrer_policy": null,
    "x_content_type_options": false,
    "mixed_content": false
  },
  "policy": {
    "url": null,
    "fetched": false,
    "language": null,
    "items": null,
    "words": 0
  },
  "requests_observed": 2,
  "disclaimer": "Automated technical signals, not legal advice. Pages change: this reflects the state at scan time.",
  "cached": false,
  "took_ms": 13858
}
```

Main response fields:

*   `scan_status`: `ok`, or `unavailable` with `unavailable_reason` (`bot_protection`, `robots_txt`, `http_error` or `unreachable`).
*   `score` and `grade`: 100 minus 20 per `high`, 8 per `medium` and 3 per `low` finding, and a grade from `A` to `F`.
*   `findings`: `id`, `severity`, `title`, `detail`, `evidence`, `recommendation` and `legal_basis`.
*   `cookies` and `third_parties`: every cookie stored and every other site contacted before consent.
*   `storage`: the localStorage and sessionStorage keys present before consent, with `area`, `origin`, `vendor` and `category` (full mode only). Lumen never reads their values.
*   `policy`: the policy URL, its language and the art. 13 items found.
*   `cached` and `took_ms`: whether the report came from the 1-hour cache, and the server time. Send `fresh` to skip the cache.

#### 3. Scan a page (GET)

Same scan as `POST /v1/scan`, with query parameters. The example is a quick scan of the same site.

**Method:** `GET`

**Endpoint:** `/v1/scan`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | A page or a domain, as in `POST /v1/scan`. | string | Yes | - | - |
| `mode` | query | `full` or `quick`. | string | No | `full` | - |
| `include_policy` | query | Fetch and check the privacy policy. | boolean | No | `true` | - |
| `fresh` | query | Skip the 1-hour cache and scan again. It still counts towards the per-site limit. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/lumen/v1/scan?url=example.com&mode=quick' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "scan_status": "ok",
  "unavailable_reason": null,
  "url": "https://example.com",
  "final_url": "https://example.com",
  "mode": "quick",
  "status": 200,
  "scanned_at": "2026-10-31T00:30:03+00:00",
  "score": 77,
  "grade": "B",
  "summary": {
    "high": 1,
    "medium": 0,
    "low": 1,
    "info": 0
  },
  "findings": [
    {
      "id": "LUM-05",
      "severity": "high",
      "title": "No privacy policy link found",
      "detail": "No link to a privacy policy was found on the page.",
      "evidence": {},
      "recommendation": "Link the privacy policy from every page (usually in the footer) and from every form that collects personal data.",
      "legal_basis": "GDPR art. 12, 13"
    },
    {
      "id": "LUM-11",
      "severity": "low",
      "title": "HSTS header missing",
      "detail": "Without Strict-Transport-Security, a first visit can be downgraded to HTTP.",
      "evidence": {},
      "recommendation": "Send Strict-Transport-Security: max-age=31536000; includeSubDomains.",
      "legal_basis": "GDPR art. 32"
    }
  ],
  "cookies": [],
  "storage": [],
  "third_parties": [],
  "consent": {
    "cmp": null,
    "banner_detected": false,
    "tcf_api": false
  },
  "google_fonts": false,
  "forms": [],
  "security": {
    "https": true,
    "hsts": false,
    "csp": false,
    "referrer_policy": null,
    "x_content_type_options": false,
    "mixed_content": false
  },
  "policy": {
    "url": null,
    "fetched": false,
    "language": null,
    "items": null,
    "words": 0
  },
  "requests_observed": 1,
  "disclaimer": "Automated technical signals, not legal advice. Pages change: this reflects the state at scan time.",
  "cached": false,
  "took_ms": 34
}
```

#### 4. List the rules

Returns the 26 rules the scanner can report, with their severity and legal basis.

**Method:** `GET`

**Endpoint:** `/v1/rules`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/lumen/v1/rules' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK, shortened to 3 of the 26 rules):**

```json
[
  {
    "id": "LUM-01",
    "severity": "high",
    "title": "Tracking cookies set before consent",
    "legal_basis": "ePrivacy Directive art. 5(3); GDPR art. 6(1)(a), 7; CJEU C-673/17 Planet49"
  },
  {
    "id": "LUM-15",
    "severity": "low",
    "title": "Cookieless analytics contacted before consent",
    "legal_basis": "ePrivacy Directive art. 5(3); EDPB Guidelines 2/2023 on art. 5(3)"
  },
  {
    "id": "LUM-16",
    "severity": "info",
    "title": "Privacy policy language not supported for the content check",
    "legal_basis": "GDPR art. 13"
  }
]
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The scan ran. A site that can't be scanned is still a 200, with `scan_status: "unavailable"` and the reason. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong. This API has `GET /v1/health`, `POST /v1/scan`, `GET /v1/scan` and `GET /v1/rules`. |
| 422 | Unprocessable Entity | `url` is missing, not an http(s) URL or domain, an IP address or a port other than 80 and 443, or `mode` is unknown. Example: `{"detail":"send a domain, not an IP address"}`. |
| 429 | Too Many Requests | You sent more than 1 request per second, or the target site had 6 new scans in the last minute from any customer (`fresh` scans included). Wait and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |

## Rate Limits

Every plan allows 1 request per second. Each request counts as one scan, and that includes `GET /v1/rules`, `GET /v1/health` and reports served from the cache: on api.market every request is a call.

Monthly quotas:

*   **Free**: 15 scans, a 7-day free trial, once per customer.
*   **Pro**: 1,000 scans per month.
*   **Ultra**: 5,000 scans per month.
*   **Mega**: 25,000 scans per month.

Calls stop when the quota runs out until the next month. Going over 1 request per second returns `429 Too Many Requests`, so back off and retry after a short pause.

## FAQ

*   **How is this different from a cookie scanner?**

    Most scanners list cookies, while Lumen reports findings with the evidence, a fix and the GDPR or ePrivacy article behind them. It also reads the privacy policy and checks third-party requests, browser storage, fonts, forms and security headers.

*   **Full or quick mode?**

    Full (the default) uses a real Chromium and catches what JavaScript and tag managers do, which is where almost all pre-consent tracking happens. Quick uses plain HTTP and answers in under a second, but only sees `Set-Cookie` headers and what the HTML references.

*   **How long does a full scan take?**

    Usually 5 to 15 seconds. In our test a full scan of example.com took about 14 seconds, and the quick scan took under a second.

*   **Is a finding a legal violation?**

    No. Findings are automated technical signals, not legal advice, and some depend on context, such as whether a cookie is strictly necessary.

*   **How are cookieless analytics and error monitoring treated?**

    Cloudflare Web Analytics, Plausible, Fathom, Simple Analytics, Pirsch and Umami Cloud get LUM-15 (low) instead of a tracking finding, when the scan sees nothing stored by them. Sentry counts as error monitoring, not tracking.

*   **Some sites come back as unavailable. Why?**

    Some sites block every request from a cloud server or opt out in robots.txt. Lumen reports that as `unavailable` with the reason, instead of disguising the scanner.

*   **I fixed my site. How do I scan it again right away?**

    Send `"fresh": true` in the POST body, or `fresh=true` on GET. It skips the cache, and it still counts towards the limit of 6 new scans per site per minute.

*   **Do you store the results?**

    Results are cached in memory for up to 1 hour so repeat calls are instant, then forgotten. We don't keep request logs with the URLs you scan.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Scan any page in a real browser for cookies, trackers, Google Fonts and forms that break GDPR before consent. 26 rules, each with its legal basis.

Lumen GDPR Website Scanner API: cookies and trackers

Lumen GDPR and ePrivacy Website Scanner