NPM features
The npm features extend the Threat Intelligence API with npm-ecosystem coverage. They run at a separate base URL, ship their own OpenAPI spec, and are available to selected partners working directly with Patchstack. The shared endpoints (/latest, /product/{type}/{name}/{version}, /product/{type}/{name}/{version}/exists, /batch) behave the same as the stable API but accept extra parameters and return a nested response shape. This page documents only what’s new — for the full spec including npm-flavour examples, see the auto-generated reference. Contact us if you’d like access.
Base URL
Section titled “Base URL”https://vdp-api.patchstack.com/database/api/npm/What’s new
Section titled “What’s new”| Addition | Where it applies |
|---|---|
GET /all | New endpoint — cursor-paginated full listing of every advisory, scoped by ?platform=. |
?platform=npm | List endpoints (/all, /latest, /product/...). Default is wordpress; case-insensitive. |
?cursor= | /all and /latest — cursor pagination alongside the existing ?page=&per_page=. |
?updated_since= | /all in cursor mode — only entries changed since a unix time. See Incremental sync. |
product.type | Every record. The product kind in lower case: plugin, theme, wordpress (core) or npm. |
?include=details | List endpoints — adds an advisory_details markdown field to each item (npm). |
| Nested response shape | All list endpoints — product, cvss, cwe, version_info objects in place of the v2 flat shape. |
The full npm-features schema (every endpoint, parameter, response example) lives in the auto-generated reference.
Pagination
Section titled “Pagination”/all and /latest support two independent strategies. Use whichever fits your client:
- Offset (
?page=&per_page=) — returns apaginationblock with totals,has_next_page,has_previous_page, etc. Easy to jump to a specific page; slower at depth and susceptible to row-shift when new advisories land while you’re paging. - Cursor (
?cursor=) — returns acursorblock withnext_cursor,has_more,per_page. Stable under concurrent inserts and faster at any depth. Nototalcount (deliberately skipped to keep cursor mode fast).
cursor and page are mutually exclusive; passing both returns 422 Unprocessable Entity. To bootstrap cursor mode, send ?cursor= with an empty value.
When a cursor is malformed (invalid base64 or missing the v1: prefix), the endpoint returns 200 with an empty page:
{ "vulnerabilities": [], "cursor": { "next_cursor": null, "has_more": false, "per_page": 100 }}Incremental sync
Section titled “Incremental sync”Mirroring the whole feed on every run is slow. After the first full listing, ask only for what changed:
- Every
/allresponse has awatermark: the unix time its rows were read. Keep the oldest one from your last sync. - Next time, walk
/all?cursor=&updated_since=<watermark>. You get the entries changed since then (new ones, and edits such as a new fixed version), and on the first pageremoved_ids: entries withdrawn since then. Replace changed entries byidand drop the removed ones. - Store the new
watermarkfor the run after that.
Starting a minute before the watermark is safe: entries are re-sent, never lost. An entry deleted outright doesn’t show up in removed_ids, so run a full listing now and then (daily is plenty). updated_since needs cursor mode; with page it returns 422 Unprocessable Entity.
curl 'https://vdp-api.patchstack.com/database/api/npm/all?platform=wordpress&per_page=500&cursor=&updated_since=1793018157' \ -H 'PSKey: YOUR_KEY'{ "vulnerabilities": [ { "id": 46510, "product": { "id": 37, "name": "…", "slug": "…", "type": "plugin" }, "…": "…" } ], "cursor": { "next_cursor": null, "has_more": false, "per_page": 500 }, "watermark": 1793018399, "removed_ids": [46412]}Scoped npm packages
Section titled “Scoped npm packages”npm package slugs that include a / (e.g. @scope/pkg) conflict with the route separator. URL-encode the / as %2F or contact us for guidance on the encoding helper.
Rate limiting
Section titled “Rate limiting”Requests are limited per API key, per minute. Single lookups (/product/..., /latest), /batch and /all each have their own allowance, so a busy batch job doesn’t use up your feed sync. /npm and the /beta alias count against the same allowance.
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Past the limit you get 429 Too Many Requests with a Retry-After header: wait that many seconds, then retry. The error field of the response names the limit you hit.
Errors
Section titled “Errors”In addition to the stable error codes, the npm endpoints return:
| Status | Meaning |
|---|---|
422 Unprocessable Entity | Invalid parameter combination (e.g. cursor + page, or updated_since without cursor), invalid platform, or per_page > 500. |
Migration notes (stable v2 → npm endpoints)
Section titled “Migration notes (stable v2 → npm endpoints)”- npm responses use nested objects (
product,cvss,cwe,capec,version_info) whereas the v2 shape is flat. Update parsers accordingly. ghsa_idwas renamed toghsaat the top level.direct_urlwas renamed tourl(the npm-flavoured shape exposes a single URL only).- The
descriptionfield was dropped for npm (the title already includes it). - The response body always contains a
vulnerabilitiesarray, plus eitherpagination(offset mode) orcursor(cursor mode).
Multi-span advisories and the fix to show
Section titled “Multi-span advisories and the fix to show”Many npm advisories affect several majors at once. Product lookups (GET /product/... and /batch) now match the installed version against every affected span, not only the lowest one.
When a version matches, the advisory includes a matched_range object beside the existing top-level fixed_in:
| Field | Meaning |
|---|---|
matched_range.from_version | Lower bound of the span that matched the installed version (nullable). |
matched_range.to_version | Upper bound of that span (nullable). |
matched_range.to_bound | How to read to_version: exclusive, inclusive, last-affected, or null when unrecorded. |
matched_range.fixed_in | The fix for this span. Use this when telling a user what to upgrade to. null means that span was never fixed. |
Top-level fixed_in / version_info.fixed remain the highest fix across every span, for backwards compatibility. Prefer matched_range.fixed_in for user-facing upgrade advice so a site on next@13 is not told to jump to a later major.
Testing
Section titled “Testing”curl — one-liners
Section titled “curl — one-liners”# Latest 24h, npmcurl 'https://vdp-api.patchstack.com/database/api/npm/latest?platform=npm&per_page=10' \ -H 'PSKey: <your-api-key>'
# Cursor pagination walk (bootstrap + follow)curl 'https://vdp-api.patchstack.com/database/api/npm/all?platform=npm&per_page=50&cursor=' \ -H 'PSKey: <your-api-key>'
# Check a specific npm package/version with full advisory textcurl 'https://vdp-api.patchstack.com/database/api/npm/product/npm/axios/0.21.4?include=details' \ -H 'PSKey: <your-api-key>'
# Boolean-only exists checkcurl 'https://vdp-api.patchstack.com/database/api/npm/product/npm/axios/0.21.4/exists' \ -H 'PSKey: <your-api-key>'Cursor iteration (JavaScript / Node)
Section titled “Cursor iteration (JavaScript / Node)”async function* allVulnerabilities(apiKey, platform = 'npm', perPage = 100) { const base = 'https://vdp-api.patchstack.com/database/api/npm/all'; let cursor = ''; // empty = bootstrap cursor mode
while (true) { const url = `${base}?platform=${platform}&per_page=${perPage}&cursor=${encodeURIComponent(cursor)}`; const res = await fetch(url, { headers: { PSKey: apiKey } }).then(r => r.json());
for (const vuln of res.vulnerabilities) { yield vuln; }
if (!res.cursor.has_more) return; cursor = res.cursor.next_cursor; }}
// usagefor await (const vuln of allVulnerabilities(process.env.PATCHSTACK_KEY)) { console.log(vuln.id, vuln.title);}Cursor iteration (PHP)
Section titled “Cursor iteration (PHP)”<?php
$apiKey = getenv('PATCHSTACK_KEY');$cursor = '';
do { $url = 'https://vdp-api.patchstack.com/database/api/npm/all' .'?platform=npm&per_page=100&cursor='.urlencode($cursor);
$ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['PSKey: '.$apiKey, 'Accept: application/json'], ]); $response = json_decode(curl_exec($ch), true); curl_close($ch);
foreach ($response['vulnerabilities'] as $vuln) { // handle $vuln }
$cursor = $response['cursor']['next_cursor'] ?? null;} while ($response['cursor']['has_more'] ?? false);More information
Section titled “More information”You can find more information about the Patchstack Threat Intelligence API on https://patchstack.com/for-hosts/. If you have integration questions, email dave.jong@patchstack.com.