API usage guide

VulnSea exposes a small, agent-friendly HTTP API over the CVE corpus — structured JSON, raw markdown, full-text search, and an incremental feed built for agents that poll for new vulnerabilities. Base URL: https://vulnsea.com.

OpenAPI 3.1 spec ↗Create an API key →

Authentication

Access is tiered. The latest 100 CVEs (by publish date) are free and need no auth. Older CVEs and full-corpus enumeration require an account — send an API key or call from a logged-in browser session. Responses include an access field (public or full).

Create a key on your account page (shown once — store it). Send it as a bearer token or x-api-key:

# bearer
curl -H "Authorization: Bearer vsk_your_key" https://vulnsea.com/api/cve

# or x-api-key
curl -H "x-api-key: vsk_your_key" https://vulnsea.com/api/cve

An invalid key → 401. No key → you still get the free public window, capped to the latest 100.

Endpoints

GET/api/cve

Paginated, filterable CVE feed.

Query params:

q — full-text filter
severity — comma list: critical,high,medium,low
vendor, exploited=true
since — ISO date or epoch ms (by ingestedAt)
order — asc | desc (default desc)
cursor — opaque, from the previous response's next
limit — 1–500 (default 50)

curl -H "$AUTH" "https://vulnsea.com/api/cve?severity=critical&limit=20"

GET/api/cve/{id}

One CVE as a structured JSON record.

curl -H "$AUTH" https://vulnsea.com/api/cve/CVE-2021-44228

GET/cve/{id}.md

Raw canonical markdown — ideal for LLM ingestion.

curl -H "$AUTH" https://vulnsea.com/cve/CVE-2021-44228.md

GET/api/digest

Compact one-line-per-CVE view for cheap triage scans.

Same filters/paging as /api/cve, plus format=json|text|ndjson.

curl -H "$AUTH" "https://vulnsea.com/api/digest?format=text&limit=50"

GET/api/search

Typo-tolerant full-text search (FTS5).

curl -H "$AUTH" "https://vulnsea.com/api/search?q=log4shell&kev=true"

GET/api/changes

Change feed: per-CVE field-change events (KEV added, severity bumped, EPSS moved) with an exact cursor — the re-triage trigger.

/api/cve?since= answers "what's new"; this answers "what changed about records you already triaged". Store the response's nextSeq, pass it as after next poll.

curl -H "$AUTH" "https://vulnsea.com/api/changes?after=$SEQ&field=kev"

GET/api/resolve

Resolve any advisory identifier (GHSA id, alias) to its canonical CVE record.

curl -H "$AUTH" "https://vulnsea.com/api/resolve?id=GHSA-jfh8-c2jp-5v3q"

GET/api/movers

EPSS movers — the CVEs whose exploit probability climbed the most over a recent window.

curl -H "$AUTH" "https://vulnsea.com/api/movers?days=14&minDelta=0.1"

POST/api/osv/v1/query

OSV-compatible query (osv.dev schema) — point existing OSV clients here unchanged; VulnSea signal rides in database_specific.

curl -H "$AUTH" -H "content-type: application/json" \
     https://vulnsea.com/api/osv/v1/query \
     -d '{"package":{"purl":"pkg:npm/[email protected]"}}'

GET/llms.txt

Machine-readable index for LLMs (llmstxt.org).

curl -H "$AUTH" https://vulnsea.com/llms.txt

Incremental polling (for agents)

To watch for new CVEs: track the highest ingestedAt you have seen (your high-water mark), then ask for everything after it, oldest → newest, paging via next until it's null. Send If-None-Match with the last ETag to get a 304 when nothing changed.

AUTH="Authorization: Bearer vsk_your_key"

# first run — page through, remember max ingestedAt → HWM
curl -H "$AUTH" "https://vulnsea.com/api/cve?order=asc&limit=100"

# each poll — only what's new since the high-water mark
curl -H "$AUTH" -H "If-None-Match: $ETAG" \
     "https://vulnsea.com/api/cve?since=$HWM&order=asc&limit=100"
#   304 => nothing new   |   200 => process, advance HWM + ETag

# cheap triage scan
curl -H "$AUTH" "https://vulnsea.com/api/digest?since=$HWM&order=asc&format=text"

Why ingestedAt? It's when VulnSea added the record — unlike published (which can be backdated), so deltas never miss a late-published CVE.

Caching & limits

Responses carry an ETag; use If-None-Match for 304 Not Modified.
The x-vulnsea-plan header reflects your tier.
Per-plan limits (saved searches, API keys, rate) are shown on your account.
Over-limit writes (e.g. too many keys) return 402.

Generate a client

Point any OpenAPI codegen / tool-use model at https://vulnsea.com/openapi.json to build a typed client or agent tool automatically.