The npm Read Path Has No Owner
Quick answer: The endpoint every npm install hits — GET /{package} — is not documented on api-docs.npmjs.com, npm's own registry API site. npm's CLI docs point instead at a CommonJS wiki specification last edited in April 2014 that never mentions the abbreviated metadata format npm actually requests. Python's and Cargo's equivalents are versioned, maintained specifications. npm's is the outlier.
Every install in the JavaScript ecosystem starts with one HTTP request: fetch the package document, read the versions and the dist-tags, pick a version, download the tarball. It is one of the most-executed HTTP requests in open-source software. It is also, as far as official documentation goes, unowned.
That is not a complaint about npm's reliability. The registry is fine. The problem is for everyone building something that talks to it: a mirror, a corporate proxy, a private registry, an SBOM scanner, an alternative client. They are all implementing a protocol that has three partial descriptions in three places, none of which is authoritative, and which disagree about scope.
What npm's API documentation actually covers
api-docs.npmjs.com describes itself as "the API documentation for the npm registry" and is thorough about the write side. It documents authentication and authorization, access grants for teams, orgs and collaborators, bulk security advisories, OIDC token exchange, org membership, package version lifecycle status, publishing via PUT /{escapedPackageName}, search, staging, teams, tokens and trusted publisher configurations.
It does not document GET /{package}. The only package-level GET endpoints on the site are the version lifecycle status and the staged-item endpoints. Public tarball downloads are absent too; the one tarball route documented is GET /-/stage/{stage-id}/tarball, for a maintainer reviewing a staged version.
The asymmetry is telling. Everything npm has invested in over the last two years — trusted publishing, stage-only tokens, OIDC, the audit endpoint migration — is documented to a reasonable standard. The part that predates all of it, and that every install depends on, is not on the site.
npm's CLI docs point at a 2014 wiki page
The npm CLI's own registry page does name a specification: "To resolve packages by name and version, npm talks to a registry website that implements the CommonJS Package Registry specification for reading package info." It gives the default registry URL, notes that npm's implementation "supports several write APIs as well", and lists no paths, no request formats and no link to the spec it just cited. Tarball downloads are not mentioned at all.
Follow the citation and you reach the CommonJS Packages/Registry wiki page. Its footer reads: "This page was last modified on 24 April 2014, at 20:28." It is a real specification, and a competent one for its era. It defines three read endpoints — registry root, {root}/{package name} and {root}/{package name}/{version} — states that "HTTP GET is the only method required for consuming the data in a package registry", allows 301 and 302 redirects, and describes the dist.tarball key as "a url to a gzipped tar archive containing a single folder with the package contents", deliberately leaving the download location to the registry. Publishing, authentication and removal are explicitly out of scope.
What it does not contain is the twelve years of behaviour npm added afterwards. No abbreviated metadata document. No content negotiation. No integrity field semantics. No dist-tag mutation rules. A client implemented strictly against this page would be correct for 2014 and would not know how to ask npm for the small payload npm itself prefers to serve.
The real description lives in a repository, with no version on it
The document that genuinely describes modern behaviour is docs/responses/package-metadata.md in the npm/registry repository, alongside a Public Registry API page that does list GET /{package} and GET /{package}/{version}. The metadata document is the good one. It explains that the abbreviated form "exists to provide a smaller payload designed to support installation", that you request it with Accept: application/vnd.npm.install-v1+json, that with no Accept header "the full document is returned", and that "for some packages in the registry, the full metadata is over 10MB uncompressed." It enumerates which fields appear in each form, and guarantees that "the name, version, and dist fields will always be present."
It is also candid in ways a marketing page never is. The dist object "is generated by npm and may be relied upon". The human-shaped fields are not: "Historically no validation has been performed on those fields." The shrinkwrap flag may be absent, in which case "the client must determine through other means if a shrinkwrap exists" — which is to say, download the tarball and look.
And here is the gap that matters: the document states no version, no stability policy and no formal status for the packument format as a whole. It is a markdown file on a default branch. There is no deprecation window, no schema version field, no process for changing it. Anyone implementing against it is implementing against a snapshot of a file that can be edited.
What a specified read path looks like
This is not an unsolvable problem, and two neighbouring ecosystems have solved it.
| Ecosystem | Where the read path is specified | Versioning |
|---|---|---|
| Python | Simple repository API spec on packaging.python.org | Declared API version plus content negotiation; history traced to ten PEPs |
| Rust | Registry index chapter of the Cargo book | Per-entry schema version field v with a forward-compatibility rule |
| JavaScript | A 2014 wiki page, a repo markdown file, not api-docs.npmjs.com | None stated |
Python's simple repository API is the interface installers use to discover projects and files, available in HTML and JSON forms, with a repository defined by its base URL and a documented history running from PEP 503 in 2015 through yank support, API versioning, standalone metadata files, content negotiation, provenance, project status markers and the 2026 HTML freeze. It is explicit about the thing npm leaves implicit too: "There are no constraints on where the files must be hosted relative to the repository."
Cargo's registry index reference goes further than any of them on operational detail. It specifies the sparse index directory layout, the one-JSON-object-per-version line format with checksums and yank flags, a config.json carrying a dl download URL template with named markers, caching through ETag or Last-Modified with 304 responses, and which status codes a registry should return for a nonexistent crate. That is a document you can build a compliant mirror from without reverse-engineering anything.
Why this costs real money
Undocumented behaviour becomes folklore, and folklore becomes incident reports. The abbreviated metadata header is the canonical example: a private registry or proxy that does not recognise application/vnd.npm.install-v1+json can reject the request outright, and the failure surfaces as a confusing install error rather than a clear protocol mismatch. The honest caveat on the table above: these three are the ecosystems checked here, not an exhaustive survey. The contrast still holds where it counts — the largest registry has the least specified read interface.
It also raises the cost of the thing the ecosystem most needs: competition at the client layer. Every alternative installer — including the ones we have covered, from pnpm's Rust rewrite to Bun — has to rediscover the same undocumented edges. The write side has a documented API, OIDC and trusted publishing. The read side has none of that, despite being the path an attacker's tarball actually travels.
The fix is unglamorous and cheap: publish the packument format on api-docs.npmjs.com with a version number and a change policy. The content already exists. It is sitting in a markdown file, waiting to be given a status.
FAQ
Is GET /{package} documented anywhere official?
Not on api-docs.npmjs.com, which documents the publish, token, stage, trust, access, org, team, audit, OIDC and search paths but no public package metadata read endpoint. It is listed in the Public Registry API markdown file in the npm/registry repository, and described in detail in that repository's package-metadata document. Neither carries a version or a formal status.
What is the abbreviated packument and why does it matter?
It is a reduced metadata document that npm serves when a client sends Accept: application/vnd.npm.install-v1+json, keeping only the fields needed for installation. npm's own documentation says it exists to provide a smaller payload for installation and that the full metadata for some packages exceeds 10MB uncompressed. Clients and proxies that mishandle the header fall back to the full document or fail the request.
Which npm metadata fields can I actually trust?
The dist object is generated by npm and, per npm's documentation, may be relied upon, and name, version and dist are always present in the abbreviated form. Publisher-supplied human fields carry no such promise: npm states that historically no validation has been performed on those fields. The shrinkwrap flag can be absent, in which case the client has to determine by other means whether a shrinkwrap exists.
Is the CommonJS Packages/Registry specification still relevant?
It is still what npm's CLI registry documentation cites, and it still accurately describes three GET endpoints and the dist.tarball convention. But its wiki footer shows a last edit of 24 April 2014, and it predates the abbreviated metadata format, content negotiation and integrity semantics that real clients depend on. Treat it as historical context, not an implementation target.
How do Python and Rust handle this differently?
Python publishes a simple repository API specification with a declared API version, HTML and JSON forms, content negotiation, and a history tracing each feature to a numbered PEP. Rust specifies the Cargo registry index in the Cargo book, including the sparse index layout, a per-entry schema version field with a forward-compatibility rule, a download URL template in config.json, and caching and status-code expectations.
Does this affect how I should run a private registry or mirror?
Yes. Because there is no versioned specification to certify against, verify behaviour empirically: confirm your proxy passes the abbreviated metadata Accept header through rather than rejecting it, check that dist.tarball URLs resolve from inside your network, and test each client you support rather than assuming protocol parity.
Explore registry and backend tooling in the API and backend category, browse open-source listings, or inspect a packument with the free JSON formatter.