Public API · v1

StackPatch HTTP API

Read-only HTTP endpoints over the same CVE index that powers the public site (41,000+ CVEs, 3,900+ packages, 5 Linux distros). Wire them into uptime monitors, security dashboards, custom alerters, or just curl them ad-hoc. No API key required for the public endpoints; one customer-token endpoint for self-serve webhook config.

Conventions

Base URL: https://mindsparkstack.com
Format: JSON (or CSV for audit export). UTF-8.
Cache: public endpoints cache 5–10 min on the edge. Hourly refresh for the CVE/package indexes.
Rate limit: 30/hr per IP on POST /api/stackpatch/quickscan. Other reads are unmetered (subject to abuse mitigation).
Versioning: response shapes are additive. We won't remove fields without notice; we may add new ones.
CORS: public endpoints allow cross-origin GET. Quickscan POST allows JSON content-type.
Errors: 4xx returns JSON {"error":"reason","hint":"..."}. 429 returns the rate-limit response with Retry-After.

Endpoints

POST/api/stackpatch/quickscanpublic · rate-limited 30/hr
Match a posted package list against the live CVE feeds. Returns findings with the exact remediation command per affected package.
Example
```
curl -X POST -H "Content-Type: application/json" \
  -d '{"distro":"ubuntu","codename":"noble","kernel":"6.8.0-100","packages":{"openssh-client":"1:9.6p1-3ubuntu13.10"}}' \
  https://mindsparkstack.com/api/stackpatch/quickscan
```
Response
JSON with outcome (vulnerable/clean/unsupported), cta_focus, headline, findings[] (id, severity, cves, command, source_url), scanned_usns, generated_at
outcomecta_focusheadlinefindings_countfindingsctagenerated_at
GET/api/stackpatch/cve/[id]public · no auth
Cross-distro inverted index for a single CVE id. Returns every (distro × package × fixed_version) combination we have on record. Backed by hourly index rebuild.
Example
```
curl https://mindsparkstack.com/api/stackpatch/cve/CVE-2023-0049
```
Response
JSON with cve, summary, first_seen, affected[] (source, ecosystem, package, fixed_version, advisory_id?, urgency?), generated_at
cvesummaryfirst_seenaffectedgenerated_at
GET/api/stackpatch/package/[name]public · no auth
All CVEs ever indexed for a specific package. Useful for "is package X having a bad week?" queries. Capped at 200 most-recent affected entries.
Example
```
curl https://mindsparkstack.com/api/stackpatch/package/openssl
```
Response
JSON with package, cve_count, ecosystems[], affected[] (cve, ecosystem, fixed_version, advisory_id, source), generated_at
packagecve_countecosystemsaffectedgenerated_at
GET/api/stackpatch/digest?days=7public · no auth
Auto-generated weekly digest: top affected packages, recent CVE drops, total cache counts. Updates every 10 minutes.
Example
```
curl 'https://mindsparkstack.com/api/stackpatch/digest?days=7'
```
Response
JSON with window_days, totals (cached_ubuntu_usns, cached_nvd_records, recent_in_window), recent[] (id, source, title, cves, affected_packages), top_packages[], generated_at
window_daystotalsrecenttop_packagesgenerated_at
GET/api/stackpatch/audit/[server]public · no auth
Per-server posture. Active findings, applied mitigations, recent resolutions, package + Docker image counts, kernel state. Same data the public audit page renders.
Example
```
curl https://mindsparkstack.com/api/stackpatch/audit/mss-vps
```
Response
JSON with server, hostname, os, kernel_running, reboot_pending, package_count, active_findings[], resolved_history[], generated_at
serveroskernel_runningfindings_activeactive_findingsresolved_historygenerated_at
GET/api/stackpatch/audit/[server]/exportpublic · no auth
Export per-server audit as CSV (one finding per row) or JSON. Suits compliance tickets + paste-into-spreadsheet workflows.
Example
```
curl 'https://mindsparkstack.com/api/stackpatch/audit/mss-vps/export?format=csv' > audit.csv
curl 'https://mindsparkstack.com/api/stackpatch/audit/mss-vps/export?format=json' > audit.json
```
Response
CSV: finding_id,severity,urgency,cves,package,installed_version,fixed_version,playbook_kind,remediation_command,title,server_slug,server_os,kernel_running,inventory_captured_at,audit_generated_at | JSON: same shape as the audit endpoint
GET/api/stackpatch/statuspublic · no auth
Service health: poller freshness, cache sizes, customer counts. Reads /var/lib/stackpatch state files directly. Wire this into your uptime monitor.
Example
```
curl https://mindsparkstack.com/api/stackpatch/status
```
Response
JSON with overall (operational/partial/degraded), checks{} (per-poller status + detail), counts{} (cached_usns, cached_nvd_records, enrolled_customers, enrolled_servers), poller_state_files{}, generated_at
overallcheckscountspoller_state_filesgenerated_at
PUT/api/stackpatch/webhookX-StackPatch-Token
Customer self-serve: attach a Discord/Slack webhook URL to a server so new-finding alerts post there in addition to email. SSRF allowlist: only discord.com + hooks.slack.com.
Example
```
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "X-StackPatch-Token: spt_..." \
  -H "X-StackPatch-Server: srv_..." \
  -d '{"webhook_url":"https://discord.com/api/webhooks/.../..."}' \
  https://mindsparkstack.com/api/stackpatch/webhook
```
Response
JSON with success, server_id, webhook_set (yes/no)
successserver_idwebhook_set

Building something on top?

Email agents@mindsparkstack.com with what you're wiring it into. We're happy to bump rate limits for legit integrations and add specifically-shaped endpoints if multiple consumers ask. Examples we'd build: a per-finding webhook (vs current per-server email), a Prometheus-format /metrics endpoint, a structured changelog feed.

Try the quickscan endpoint Service status (live)llms.txt for AI agents