HTTP API#
scanprivacy serve --port 8099 starts it on loopback. Every /v1 route requires SCANPRIVACY_API_KEY when one is configured; /healthz is always open and carries the AGPL section 13 source offer.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/scans |
submit {"url": ...}; returns 202 and a scan id |
| GET | /v1/scans/{id} |
status and result |
| GET | /v1/scans/{id}/graph |
nodes and edges |
| GET | /v1/scans/{id}/report?lang=it |
Markdown report |
| GET | /v1/scans/{id}/report.pdf?lang=en |
PDF with the full evidence |
| GET | /v1/scans/{id}/inventory |
recipients, shaped for an Art. 30 record |
| GET | /v1/rules, /v1/remediation, /v1/vendors, /v1/locales |
the loaded catalogues |
| GET | /healthz |
liveness and source offer |
Status and errors#
POST /v1/scans answers 202 with an id. GET /v1/scans/{id} answers 200 for a scan in any state and carries status (queued, running, done, error); a failed scan is a 200 with status: "error", an error text and an error_ref to quote to the operator, so a poller has one shape to read. The sub-resources (graph, report, inventory, ...) answer 409 until the scan is done. Other errors use FastAPI's {"detail": ...} shape:
| Code | Meaning |
|---|---|
| 400 | invalid URL or unknown locale |
| 401 | missing or wrong API key |
| 403 | target refused: not a public address (checked before the scan starts), or no API key is configured and the caller is not on this machine |
| 404 | unknown scan id |
| 409 | the scan is not finished |
| 429 | too many scans queued or running; honour retry-after |
| 500 | a stored result exists and cannot be read |
| 503 | results cannot be stored right now (also /healthz) |
A scan id stays valid across restarts and in-memory eviction: results are read back from disk, and a result whose stored evidence no longer matches its digest is refused with a 500. A scan that was accepted but did not finish because the service stopped (including a crash) is reported as status: "error". A scan whose browser reaches a non-public address after the pre-flight check ends as status: "error" too, not as a 403: the request was refused by the egress proxy and nothing is returned.
url is limited to 2048 characters and the optional context object to 8192 bytes when serialised.
Targets are resolved and must be public addresses, both before the fetch and for the addresses the browser actually reached (403 target refused otherwise).
Limits, all environment variables: SCANPRIVACY_MAX_CONCURRENT_SCANS (3), SCANPRIVACY_MAX_SCANS_IN_FLIGHT (50, beyond it 429 with retry-after), SCANPRIVACY_SCAN_RETENTION (200 results in memory).