API reference

The registry serves the npm registry protocol. The npm CLI, bun, and other npm clients use it without changes. This page lists each route, the rules that each route applies, and the features that are not available yet.

The examples use example.com for the site. In local development, the site is localhost:9876, and the other hosts are its subdomains, such as registry.localhost:9876.

Hosts#

A request to any other host gets 404. The slug public is reserved.

Authentication#

Send a token with Authorization: Bearer TOKEN. A token starts with nextpm_. A password never works as a credential, so HTTP Basic authentication gets 401: a password can be phished, and stuffed from other sites' leaks.

No token can write alone. Each write of an npm login token waits for its owner's passkey (see Approvals). A token from settings or npm token create, and an Org token, can only read. CI publishes with trusted publishing.

A request with an invalid or revoked token gets 401 with www-authenticate: Bearer. This also applies to reads of public packages. The login routes are the only exception. A token revoke or an Org membership change applies at the next request.

Errors use the npm form, { "error": "message" }. A private package that you cannot read gets 404, the same as a package that does not exist.

Approvals#

Each write of an npm login token, such as a publish, a dist-tag, an owner change, or npm trust, waits for a passkey approval of that exact request. This is npm's web two-factor flow, so npm 9 and later, pnpm, and Bun handle it in a terminal. Yarn asks for a typed code, so it cannot write. The steps:

1. The write gets 401 with www-authenticate: OTP and { error, authUrl, doneUrl }.
2. npm prints authUrl, a website page that shows the change, where it came from, and a warning when the browser is on another network. The person approves it with their passkey, or refuses it.
3. npm polls doneUrl, with any method: 202 with retry-after: 1 while it waits, then 200 with { "token" } once, or 404 when it was refused or expired.
4. npm sends the write again with npm-otp: TOKEN. The code works once, only for the same token, method, path, and body, within 5 minutes of the request. Any other request with it gets 401.

A token can have 20 writes waiting at once; the next gets 429. Some writes need no approval: npm logout, a staged publish (its approval comes later), audits, and the tarball delete that npm sends after an unpublish, which changes nothing.

A website session approves its package changes the same way: trusted publishers, staged versions, and whether CI releases wait. Its account changes use a 10-minute window that a passkey opens instead (see Account).

The first four routes are for the website session of the token's owner. An approval of another account answers 404.

Configure npm#

registry=https://registry.example.com/
//registry.example.com/:_authToken=${NPM_TOKEN}

@acme:registry=https://acme-internal.registry.example.com/
//acme-internal.registry.example.com/:_authToken=${NPM_TOKEN}

The second pair of lines sends the @acme scope to a private registry. The same user token works on each host. A token in CI only reads, to install private packages; run npm login to publish from a terminal.

Packages#

A package name in a path can be name, @scope%2fname, or @scope/name.

Packuments#

The full packument has the same keys and key order as npmjs: _id, _rev, name, dist-tags, versions, time, maintainers, the root fields of the latest version, readme, and readmeFilename. Each version has _id, _npmUser, maintainers, directories, _hasShrinkwrap, and a dist with integrity, shasum, tarball, fileCount, unpackedSize, and signatures. The registry moves readme from the version to the root.

The abbreviated packument has only name, dist-tags, versions, and modified. Each version has only the install fields. Unlike npmjs, it also keeps libc.

Both packuments send etag, last-modified, and vary: accept-encoding, accept. A matching if-none-match gets 304. A public package sends cache-control: public, max-age=300. A restricted package sends cache-control: private, max-age=0, must-revalidate. ?write=true always returns the full packument.

Publish#

The body is the document that npm publish sends. The registry checks each tarball against its manifest and the dist hashes that the client sent. Then it stores the tarball and adds the registry fields and signatures.

• A user must confirm their email address before they publish. Until then, a publish gets 403. A trusted publisher and an Org token are not users, so the rule does not apply to them.
• An unscoped package is public. Only a user token can create one, and only on the public registry.
• A scoped package needs the scope owner: the user with the scope's name, or a member of the Org with the scope's name. An Org token cannot publish: Org CI publishes with trusted publishing.
• A new scoped package is restricted, unless the body has "access": "public". A package in a private registry is always restricted.
• After the package exists, its maintainers and, for an Org scope, the Org members can publish.
• A version number cannot be used again, also after an unpublish. The response is 403.
• When the package has no latest tag, the first published version gets it.
• A body with a <name>-<version>.sigstore attachment, as npm publish --provenance sends, must hold a valid Sigstore bundle v0.3 with SLSA provenance v1 for that tarball. The registry checks the signature, the Fulcio certificate chain, the certificate transparency timestamp, and the Rekor entry against the public Sigstore root. The build must be from a public GitHub repository on a GitHub-hosted runner, and the repository must match repository in package.json. An invalid bundle gets 422.

Trusted publishing#

A GitHub Actions job can publish without a stored token, as on npmjs. npm 11.5.1 and later does this by itself. The job sends its OIDC identity token, with the audience npm:<registry host>, to POST /-/npm/v1/oidc/token/exchange/package/:name. When the token matches a trusted publisher of the package, the response is 201 with { "token" }: a token that can publish only this package, for 15 minutes. It cannot change tags, owners, access, or other packages. Each identity token can be exchanged once. A version from trusted publishing has _npmUser set to GitHub Actions, with trustedPublisher: { id, oidcConfigId }.

A trusted publisher matches the token's issuer, its repository_owner_id, its repository_id, its workflow file, and its environment. The environment is required, so that its protection rules in the repository guard each publish. It matches no names, so a renamed repository keeps working and a new repository with an old name never matches. A provenance bundle in a trusted publish must name the same repository_id, or the publish gets 403.

The package's website settings, and npm trust, add and remove trusted publishers, and a passkey approves each change. The repository must belong to the person's linked GitHub account, or to the GitHub organization linked to the Org that owns the package. The publisher pins that owner's id. A public repository also pins its id at once; a private one pins it on its first exchange. A scoped name that is not published yet can have trusted publishers too, from the members of its scope. Its first trusted release always stages. Once a member of its scope approves it, it creates the package, with the person who added the publisher as its maintainer.

GET /-/v1/account/pending and GET /-/org/:org/pending list the names of a scope that have trusted publishers and wait for their first publish.

The token must also come from a push, release, workflow_dispatch, or schedule event. A pull request, a comment, or a workflow_run can run code that an outsider controls, so their tokens get 401. The runner must be GitHub-hosted (runner_environment: github-hosted).

The registry trusts https://token.actions.githubusercontent.com. A deployment can trust other issuers, such as GitHub Enterprise Server, with OIDC_ISSUERS: {"https://ghes.acme.dev/_services/token":{"provider":"github","runners":"self-hosted"}}. Their runners must be hosted too, unless the entry sets "runners": "self-hosted". An entry cannot change the built-in issuer. Only github.com publishers can be added for now, because a linked GitHub account vouches only for github.com ids.

Staged publishing#

Each release from a trusted publisher waits in the package's stage until a maintainer approves it with a passkey, so a workflow that someone changed cannot ship a version alone. A maintainer can turn this off for a package, on its Publishing page. A direct trusted publish of a package that stages gets 403; run npm stage publish instead. A person can stage a version too, with no approval yet. The first version of a name outside the person's scopes cannot stage: nobody could approve it yet. Approving a stage checks the stager's current rights again, and only a new package takes the access that its stage asks for; the approval page names that access. A trusted publish never changes the access of a package that exists.

Attestations#

GET /-/npm/v1/attestations/:name@:version returns { attestations: [{ predicateType, bundle }] } for a version with provenance, as npmjs does. Such a version has dist.attestations with url and provenance.predicateType. The registry does not add its own publish attestation yet, because that needs an entry in the public Rekor log.

Document updates#

A PUT without attachments changes only these fields. npm sends the whole document back, so the other fields can come back unchanged. A changed value of any other field gets 400, and the error names the field. The registry never ignores a change.

A published version's manifest cannot change, apart from deprecated. A changed manifest gets 403 with "Changing published version metadata is not allowed", as npm's registry answered. A version that is not published gets 400; publish it with its tarball. A body that removes every version gets 400. Use DELETE /:name/-rev/:rev instead. A body with only users gets 400, because stars are not available.

Package settings#

Accounts#

Account#

These routes are for website sessions only. The website's origin and host, from WEB_URL, are the passkey origin and relying party.

A user name has 1 to 39 lowercase letters, digits, or hyphens. Sign up on the website, then run npm login, which opens the website to approve the login with a passkey.

A web login session expires after 10 minutes.

A website session token lives 30 days. It can manage the account, its tokens, and its Orgs within 10 minutes after a passkey confirmed it. It cannot publish. It changes a package's trusted publishers and staged versions only with a passkey approval of each change.

A profile of a user is { kind: "user", name, created, github, orgs, packages, weekly }; the user also sees their email, and the role and visibility of each Org. A profile of an Org is { kind: "org", name, created, registry, github, members, packages, weekly }. packages lists each package with its version, description, date, and weekly downloads, and weekly is their sum. github is the verified { id, login }, or null. The registry trades the OAuth code with GitHub itself, so a caller cannot claim a GitHub account that it did not sign in to. Linking needs GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET on the api Worker.

Mail#

The registry sends mail from MAIL_SENDER through Azure Communication Services Email. Mail is off unless MAIL_URL and MAIL_SENDER are set.

A new account gets a link to confirm its address. The link works one time, for 1 hour, and the registry keeps only a hash of its code. The link opens a page on the website that confirms only when the person presses its button, because mail scanners open links on their own. A confirmed address stays until a new one is confirmed, and it gets a notice of the change. An unconfirmed address changes at once.

An unconfirmed address gets only its confirmation mail. A confirmed address gets these notices:

Each User cell keeps its mail in an outbox, and its alarm sends each message with the message id as the operation id, so a retry never sends a message twice. Package cells keep their notices until each User cell takes them.

Tokens#

The POST body accepts name and expires (days). A new token can only read: readonly: false, packages_and_scopes_permission: "read-write", or bypass_2fa gets 400. A read-only token can live without an expiry. A login with npm login gives a token that lives 30 days, and whose writes each wait for a passkey approval.

Orgs#

These routes are not part of the npm protocol. npm org uses only the /user routes.

The roles are owner, admin, and developer. Every member can read the Org's packages, and publish them with npm login and a passkey approval of each write. Owners and admins can change members. Only an owner can grant or remove the owner role. An Org always keeps one or more owners. A member can remove themselves. Each membership is private until its member makes it public.

Private registries#

Each create or change waits for a passkey approval (see Approvals). The caller must own each scope: the scope is the caller's user name, or an Org where the caller is an owner. A scope can belong to only one private registry. When a scope moves to a private registry, its existing packages move with it and become restricted. After the move, the public host answers 404 for these packages.

A private registry serves the packages of its scopes. Readers are the scope's user, and the members of each Org scope, with a user token or an Org token.

A reader can also publish any other name to a private registry, such as a patched copy of a public dependency. The copy belongs to the registry, so every reader can publish new versions of it. It is always restricted, and it never changes the public package of the same name.

With passthrough on, the registry answers its readers for names that it does not hold with the public registry's packages, so a team can use the private host as its only registry. A name in one of the registry's scopes, or one that the registry holds, never passes through. Passthrough is off by default.

Passthrough to npm#

Until the backfill brings npm's packages here, the public registry can pass the names that it never held to an upstream registry, set by PASSTHROUGH_URL. Packuments and version manifests pass through with cache-control: public, max-age=300. Their tarball URLs still point at the upstream. A name that this registry ever held, or a name in a scope that it knows, never passes through. While passthrough is on, a new name that the upstream has cannot be published here.

POST /-/npm/v1/security/advisories/bulk (npm audit) and POST /-/npm/v1/security/audits/quick (pnpm audit, yarn audit) go to the upstream too. Before they leave, the registry removes every name in a scope that it knows, so the names of restricted packages stay here. A private registry with passthrough audits for its readers, and also removes the names that it keeps its own copies of.

Search#

GET /-/v1/search?text=TEXT&size=20&from=0

size is 1 to 250. The words of text match the name, description, keywords, author, and maintainers. The last word also matches as a prefix. These qualifiers filter the results: keywords:a,b, maintainer:name, author:name, and scope:name.

The response has the npmjs form: { objects, total, time }. Each object has package, downloads (weekly and monthly), score, searchScore, updated, flags, and dependents. dependents is always 0.

The public registry indexes only public packages. A private registry indexes all of its packages, and only its readers can search it. The index updates a short time after each change. Download totals in the index update once each day.

Front page#

GET /-/v1/front returns the totals and lists that the website's front page shows. Only the public registry host answers it, with cache-control: public, max-age=300.

Each list entry has name, version, description, published, created, publisher, weekly, integrity (of the latest version), and provenance. Each Package cell adds its downloads to the totals once a day, and again after midnight for the rest of a day it counted. The counts that scan the index can be up to 10 minutes old.

Signatures#

GET /-/npm/v1/keys returns the registry's public key, in the npmjs form. Each version has dist.signatures: an ECDSA P-256 signature of name@version:integrity, in base64 DER. The keyid is the OpenSSH SHA256: fingerprint of the key. npm audit signatures verifies these signatures.

Downloads API#

These routes are on the api. host. The paths and responses are the same as api.npmjs.org. A scoped package's counts come from the registry that its scope is bound to.

A period is last-day, last-week, last-month, last-year, a day such as 2026-10-01, or a range such as 2026-01-01:2026-03-31. A range can be 550 days or less. The named periods end on the last complete day, in UTC. A day or range can include today, so it shows counts in real time.

A bulk query can name 128 or fewer packages, and none can be scoped. A restricted package needs a token that can read it. Each response sends content-type: application/json; charset=utf-8 and cache-control: public, max-age=300.

Not available#