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 only rescanned when it changes, roughly once a day at most. Requesting a package's score more often than that 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 |
The scan-trigger endpoint also draws from a shared daily budget across all callers. When that budget
is exhausted, the endpoint returns a 503 with a Retry-After header — please
respect it rather than retrying immediately.
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.
<a href="https://plumb.dev/vendor/name">Powered by Plumb</a>
For endpoint details, request/response shapes, and to try requests live, see the API reference.