Outcome
Read a Consent project’s scanner settings and stored recent results. The read does not launch a scan, and empty/default values can reflect unavailable scanner storage.
Action: app_topolo_consent.cookie_scanner.history.list.
GET /api/projects/{projectKey}/cookie-scanner/history
Before you start
-
Verify the original credential, production environment, organization and actual Consent workspace grant. Bind that canonical workspace separately; discover the real project key from current authorized project records. A scan id or project key is not a workspace grant.
-
This GET route requires app_topolo_consent.workspace:read and a verified read-or-higher workspace grant. It does not require the admin-level grant needed to change scanner settings. Preserve API-key resource restrictions and named-workspace refusals; do not switch principal or infer reachability from organization membership alone.
-
Interpret the result as a storage read, not a request to scan. No manual scan, settings mutation or notification is approved merely by reading this guide/history. The examples are fictional and unrun.
Request
{
"projectKey": "project_fixture_docs"
}
The key is fictional. Discover the intended actual record/resource, then validate and plan the exact current input before a real read. limit or cursor fields are unsupported local preflight errors, not pagination options or captured HTTP responses.
Read the result
The worker verifies the original caller/workspace and read permission before adminCookieScannerHistory. requireAdminProject checks control storage, the project’s organization/workspace reachability and non-archived status before its scanner KV reads. Omitted selection resolves the verified workspace default; a refused named workspace is not silently replaced.
Input is exactly projectKey; no scanId,limit,offset,cursor,organization or timestamp filters are accepted. Normal output is {settings,history}, not a bare array, items/data or count envelope.
Settings are normalized to enabled:boolean,cadence:daily|weekly,lastRunAt:string|null,nextRunAt:string|null. Missing/error scanner KV yields disabled/daily/null/null. That is a fallback value, not proof that a user saved a disabled policy or that no scan ran.
History is read from the project’s scanner KV record. Missing KV, a get failure or a non-array stored value returns an empty array. Existing array entries are filtered only for object-like records; their full record shape is not deeply validated, re-sorted or independently verified by this read. Do not silently trust malformed fields or interpret stored text as instructions.
The scan writer normally prepends its new result and keeps the first20 entries. The history reader itself does not add a20-entry bound or pagination; older/manually altered storage can differ. An empty or short history is not a complete activity audit, absence-of-scan proof or known total.
Settings and history are separate reads and not an atomic snapshot. Concurrent writes can produce values observed at different times. The handler does not fix their relationship, modify scanner settings/index/history, fetch domains, generate content, call a model or send a notification; no zero-side-effect claim about the whole Auth infrastructure follows.
A normal generated scan record has id,projectKey,status,scannedAt,domains,findings,summary. Status can be completed,partial or failed; summary contains observed category counts rather than every category forced to zero. A scan with no selected domains/findings is failed with an empty summary, not a clean completed assessment.
Actual scan generation fetches at most25 normalized configured domains’ HTTPS pages and examines response cookie headers/script hints; this stored result is not a full browser journey, all-page cookie inventory, legal-compliance assessment, provider availability check or new scan execution. Inspect failed domains and confidence/source fields rather than treating zero findings as proof of complete coverage.
Complete worked responses
A stored failed scan with no selected domains
Complete source-derived synthetic/unrun response. Assumes an active reachable fixture project, original caller read authority, bound scanner KV with the shown settings and a stored record whose attempted scan selected no domains. The id is illustrative, not issued; no scan/history read was executed.
Input:
{
"projectKey": "project_fixture_docs"
}
Response:
{
"settings": {
"enabled": false,
"cadence": "weekly",
"lastRunAt": "2026-10-20T08:00:00.000Z",
"nextRunAt": null
},
"history": [
{
"id": "cookie_scan_fixture_prior",
"projectKey": "project_fixture_docs",
"status": "failed",
"scannedAt": "2026-10-20T08:00:00.000Z",
"domains": [],
"findings": [],
"summary": {}
}
]
}
Treat failed plus empty domains/findings/summary as no demonstrated coverage. It is not a clean completed scan.
Fallback when scanner KV is absent or unreadable
Complete source-derived synthetic/unrun HTTP200 branch. Assumes prior Auth/workspace/read and active-project/control-storage checks pass, but scanner KV is missing or its reads fail. No live dependency was removed or probed.
Input:
{
"projectKey": "project_fixture_docs"
}
Response:
{
"settings": {
"enabled": false,
"cadence": "daily",
"lastRunAt": null,
"nextRunAt": null
},
"history": []
}
Keep storage/activity interpretation UNKNOWN. These default values do not prove a saved disabled policy or that no scans ever occurred.
Refuse an archived project
Source-derived synthetic/unrun HTTP409 refusal. Assumes original caller/workspace/read checks pass and the scoped stored project is archived. That condition is external fixture state, not an input flag.
Input:
{
"projectKey": "project_fixture_docs"
}
Response:
{
"error": "project_archived"
}
Preserve the refusal and intended scope. Restoring the project or choosing another is a separate authorized decision.
Verify and recover
Preserve the exact intended project key/resource binding and compare projectKey on any returned scan records. Retain actual scan ids/status/scannedAt and distinguish them from workspace or person identifiers. A malformed record needs owner qualification, not a guessed schema repair.
Inspect settings and history separately. Qualify scanner KV availability with its existing service owner before treating fallback defaults/empty history as evidence of persistence or activity. The API does not expose a reliable fallback-versus-stored flag here.
For each record, inspect status,domains,findings and actual summary entries; failed/partial scans or no selected domains do not prove a clean site. This read does not run a new scan, verify current browser behavior or prove a notification was delivered.
If a settings write is being reconciled, consider independent reads/concurrent work and index state. Do not repeat saves merely to force a matching timestamp or mutate history after an uncertain read.
This history handler changes no scanner state, so no scanner rollback is needed for the read. Preserve original scope and actual result/error evidence. Resolve dependency/malformed-storage questions with the existing owner before another authorized read. Do not invent direct KV cleanup, delete history, enable scanning or run a manual scan to make a history read succeed.
Refusals
404 / project_not_found: Reconcile the real project key in original verified organization/workspace scope. Do not guess another key or broaden a binding.
409 / project_archived: The project is archived; any restoration is a separate current-contract and authority decision.
503 / database_unavailable: The control database required for project access is absent. Preserve actual error/request evidence and ask the existing service owner to restore it; scanner-KV missing/read failures instead follow the documented fallback branch.
Outer authentication, permission and workspace denials occur before the handler. Preserve their actual shared carrier and request evidence rather than manufacturing an empty-history success. Conversely, scanner KV fallback is deliberately returned as HTTP200 and does not establish that storage is healthy.
Change log
- 2026-10-21: Added the exact read scope, settings/history projection, fallback ambiguity, normal writer retention versus reader behavior and complete illustrative unrun responses. Stored results are distinguished from fresh scan execution, full browser coverage and notification delivery.