HTTP endpoints
pnpr exposes one always-on health endpoint plus two configurable surfaces:
- Registry surface (
registry.enabled) - npm-compatible package, auth, and publish endpoints. - Resolver surface (
resolver.enabled) - pnpr install-accelerator endpoints under/-/pnpr.
Both surfaces are enabled by default. See Configuration for the config keys and CLI reference for the command-line overrides.
Always available
| Method | Path | Description |
|---|---|---|
GET | /-/ping | Health check. Returns {}. |
Resolver endpoints
The resolver endpoints are mounted when resolver.enabled is true. The
POST endpoints require a valid pnpr Authorization header.
| Method | Path | Description |
|---|---|---|
GET | /-/pnpr | Capability handshake. Returns supported protocol versions, currently {"pnpr":{"versions":[0]}}. A 404 means the server has no compatible resolver surface. |
POST | /-/pnpr/v0/resolve | Resolves one project or workspace against the registries and policy sent by the client. Returns application/x-ndjson frames. |
POST | /-/pnpr/v0/verify-lockfile | Verifies an existing lockfile under the client's registry and policy settings without resolving again. Returns application/x-ndjson frames. |
POST /-/pnpr/v0/resolve accepts fields such as projects, dependencies,
devDependencies, optionalDependencies, registry, namedRegistries,
authHeaders, overrides, lockfile, frozenLockfile,
preferFrozenLockfile, ignoreManifestCheck, trustLockfile,
minimumReleaseAge, minimumReleaseAgeExclude,
minimumReleaseAgeIgnoreMissingTime, trustPolicy, trustPolicyExclude, and
trustPolicyIgnoreAfter.
The resolve response is an NDJSON stream:
| Frame | Description |
|---|---|
package | One resolved tarball: id, name, version, integrity, tarball, and optional unpackedSize / fileCount. |
done | Terminal success frame. For resolve, carries lockfile and stats.totalPackages; for verify-lockfile, only indicates success. |
violations | Terminal policy failure frame. Carries rendered lockfile or OSV violations. |
error | Terminal server-side resolution or verification error. |
Registry read endpoints
These endpoints are mounted when registry.enabled is true. Package reads are
checked against the matching package rule's access list.
| Method | Path | Description |
|---|---|---|
GET | /{name} | Unscoped package packument. |
GET | /@scope/{name} | Scoped package packument. |
GET | /{name}/{version-or-tag} | Unscoped version manifest by exact version or dist-tag. |
GET | /@scope/{name}/{version-or-tag} | Scoped version manifest by exact version or dist-tag. |
GET | /{name}/-/{filename} | Unscoped tarball. |
GET | /@scope/{name}/-/{filename} | Scoped tarball. |
GET | /-/package/{package}/dist-tags | Package dist-tags object. Use a percent-encoded scoped package name, for example @scope%2Fname. |
GET | /-/v1/search?text=<query>&size=<n> | npm search v1 shape. Searches hosted packages by package-name substring and may add an exact upstream match. Results are filtered by access policy. |
Packument responses rewrite dist.tarball URLs to the configured
public_url. If the client sends
Accept: application/vnd.npm.install-v1+json, pnpr returns npm's abbreviated
install-v1 packument shape.
When OSV checks are enabled, vulnerable versions are removed from packuments and dist-tags. Version manifests and tarballs for vulnerable versions are denied.
Registry write endpoints
These endpoints are mounted when registry.enabled is true. PUT and
DELETE requests require credentials. A read-only bearer token cannot use
write methods, and CIDR-restricted bearer tokens are checked against the peer
socket address.
| Method | Path | Description |
|---|---|---|
PUT | /{name} | Publish an unscoped package. Body is the npm publish document with _attachments. Requires publish. |
PUT | /@scope/{name} | Publish a scoped package. Body is the npm publish document with _attachments. Requires publish. |
PUT | /-/pnpm/v1/publish | pnpm batch publish. Body is {"packages":[<publish document>, ...]}. The batch is all-or-nothing and each package requires publish. |
PUT | /{package}/-rev/{rev} | Replace a packument, used by partial unpublish. Requires both publish and unpublish. Use a percent-encoded scoped package name, for example @scope%2Fname. |
DELETE | /{package}/-rev/{rev} | Remove an entire package, used by force unpublish. Requires unpublish. Use a percent-encoded scoped package name for scoped packages. |
DELETE | /{name}/-/{filename}/-rev/{rev} | Remove an unscoped tarball. Requires unpublish. |
DELETE | /@scope/{name}/-/{filename}/-rev/{rev} | Remove a scoped tarball. Requires unpublish. |
PUT | /-/package/{package}/dist-tags/{tag} | Add or update a dist-tag. Body is a JSON string version, for example "1.0.0". Requires publish. |
DELETE | /-/package/{package}/dist-tags/{tag} | Remove a dist-tag. Requires publish. |
User and token endpoints
These endpoints are mounted when registry.enabled is true.
| Method | Path | Description |
|---|---|---|
PUT | /-/user/org.couchdb.user:{name} | npm adduser/login endpoint. Creates a user only when auth.htpasswd.max_users allows registration; existing users can log in with the correct password. Returns a bearer token. |
GET | /-/whoami | Returns {"username": ...} for the authenticated caller. |
GET | /-/npm/v1/user | npm profile endpoint. Returns the authenticated username and placeholder profile fields. |
GET | /-/npm/v1/tokens | Lists bearer tokens for the authenticated caller in npm-compatible shape. |
DELETE | /-/npm/v1/tokens/token/{key} | Revokes one of the caller's tokens by listing-side token key. |
DELETE | /-/user/token/{token} | npm logout endpoint. Revokes the raw bearer token in the path when it belongs to the authenticated caller. |