API usage guidelines
The public API is free to use, with no key required. If you're displaying Plumb scores on your own site, here's what we ask in return.
Caching
A package is re-evaluated on its scan cadence (daily for most tiers) but its deep data is only re-fetched when the source actually changes; identical results coalesce, so last_checked_at advances while results_changed_at marks the last real change. Requesting a package's score more often returns the same result — please cache responses for at least 24 hours rather than fetching on every page view.
If you just need a visual badge, embed the SVG endpoints directly (see the "For Maintainers" section on any package page) — they're small, cacheable images and don't count against the JSON API's rate limits below.
Rate limits
Limits are enforced per IP address.
| Endpoint | Limit |
|---|---|
Read endpoints (GET) |
120 requests per minute |
Scan trigger (POST) |
3 requests per 15 minutes · 30 per day |
Plumb reserves the right to block requests or IP addresses that abuse these limits.
Attribution
You're welcome to display Plumb scores publicly — that's what the API is for. In return, any public display of a score must include clear, prominent attribution near the score: the phrase "Powered by Plumb", with "Plumb" linked back to either the Plumb homepage or, preferably, the package's own Plumb page.
Powered by <a href="https://plumb.dev/vendor/name">Plumb</a>
For endpoint details, request/response shapes, and to try requests live, see the API reference.
