API reference for scans, issues, reports, and settings.

Use these examples against Shopkeeper on port 8080 or through the dashboard proxy where applicable. Endpoints are grouped by method so reads, lifecycle actions, settings updates, and deletes stay easy to scan.

GET

GET endpoints

Read scans, issue groups, report files, health, version, and settings.

GET/api/scansScans

List scans

Returns all scans, newest first. Supports optional tag filtering.

Auth

None in self-hosted v1.0.

Response

Array of scan records with URL, status, progress, viewport, tag, and timestamps.

Example

curl -s -X GET "http://localhost:8080/api/scans"

GET/api/scans/{id}Scans

Get scan

Returns one scan record and current lifecycle state.

Auth

None in self-hosted v1.0.

Response

Scan record or 404.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID"

GET/api/scans/{id}/issuesIssues And Reports

Legacy issue list

Returns all failed issues and occurrences for a scan.

Auth

None in self-hosted v1.0.

Response

Array of issues with occurrences.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues"

GET/api/scans/{id}/issues/chunksIssues And Reports

Issue summary chunk

Returns a bounded page of failed and needs-review issue cards.

Auth

None in self-hosted v1.0.

Response

Issue summaries and aggregate counts.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues/chunks"

Use this for large scans instead of loading every occurrence up front.

GET/api/scans/{id}/issues/detailsIssues And Reports

Issue detail

Returns one issue group with paginated occurrences.

Auth

None in self-hosted v1.0.

Response

Issue summary, detail metadata, and occurrence page.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues/details"

GET/api/scans/{id}/issues/report.pdfIssues And Reports

PDF report

Generates a full scan or scoped issue PDF report.

Auth

None in self-hosted v1.0.

Response

PDF file download.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues/report.pdf"

GET/api/scans/{id}/issues/report.csvIssues And Reports

CSV report

Downloads a full or small CSV report.

Auth

None in self-hosted v1.0.

Response

CSV file download.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues/report.csv"

Use mode `small` for all issues with sampled occurrences and mode `full` for every occurrence.

GET/api/scans/{id}/issues/report.llm.txtIssues And Reports

LLM report

Downloads a compact text report designed for LLM review.

Auth

None in self-hosted v1.0.

Response

Plain text file download.

Example

curl -s -X GET "http://localhost:8080/api/scans/$SCAN_ID/issues/report.llm.txt"

GET/api/healthSettings And Runtime

Health check

Returns Shopkeeper service health.

Auth

None.

Response

{ status, service }

Example

curl -s -X GET "http://localhost:8080/api/health"

GET/api/versionSettings And Runtime

Version

Returns build version and commit metadata.

Auth

None.

Response

{ version, commit }

Example

curl -s -X GET "http://localhost:8080/api/version"

GET/api/settingsSettings And Runtime

Read settings

Returns reporting, performance, and integration settings.

Auth

None in self-hosted v1.0.

Response

Grouped server settings.

Example

curl -s -X GET "http://localhost:8080/api/settings"

POST

POST endpoints

Create scans or trigger scan lifecycle actions.

POST/api/scansScans

Create scan

Creates a sitemap or single-page scan and starts the async scanner.

Auth

None in self-hosted v1.0.

Response

Created scan record.

Body

{ sitemap_url, scan_type, tag?, viewport_preset? }

Example

curl -s -X POST "http://localhost:8080/api/scans" \
  -H "Content-Type: application/json" \
  --data '{ sitemap_url, scan_type, tag?, viewport_preset? }'

Use scan_type `single` for one URL and `sitemap` for sitemap discovery.

POST/api/scans/{id}/retry-failedScans

Retry failed pages

Requeues failed pages inside the same completed partial scan.

Auth

None in self-hosted v1.0.

Response

Same scan record plus retried URL count.

Example

curl -s -X POST "http://localhost:8080/api/scans/$SCAN_ID/retry-failed"

This does not create a new scan ID and leaves completed pages intact.

POST/api/scans/{id}/rescanScans

Full rescan

Creates a new scan using the original target and viewport.

Auth

None in self-hosted v1.0.

Response

New scan record.

Example

curl -s -X POST "http://localhost:8080/api/scans/$SCAN_ID/rescan"

POST/api/scans/{id}/pauseScans

Pause scan

Requests a cooperative pause for an active scan.

Auth

None in self-hosted v1.0.

Response

Updated scan record.

Example

curl -s -X POST "http://localhost:8080/api/scans/$SCAN_ID/pause"

POST/api/scans/{id}/resumeScans

Resume paused scan

Reopens a paused scan and continues pending pages.

Auth

None in self-hosted v1.0.

Response

Updated scan record.

Example

curl -s -X POST "http://localhost:8080/api/scans/$SCAN_ID/resume"

PUT

PUT endpoints

Update server-wide settings.

PUT/api/settingsSettings And Runtime

Update settings

Updates server-wide reporting, performance, and integration settings.

Auth

None in self-hosted v1.0.

Response

Updated grouped server settings.

Body

{ reporting?, performance?, integrations? }

Example

curl -s -X PUT "http://localhost:8080/api/settings" \
  -H "Content-Type: application/json" \
  --data '{ reporting?, performance?, integrations? }'

DELETE

DELETE endpoints

Remove scan data and stored screenshots.

DELETE/api/scans/{id}Scans

Delete scan

Deletes the scan, related database rows, and stored screenshots.

Auth

None in self-hosted v1.0.

Response

204 on success.

Example

curl -s -X DELETE "http://localhost:8080/api/scans/$SCAN_ID"