A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The npm API is how an app or AI agent works with the npm registry: reading a package's metadata, searching for packages, publishing new versions, and moving distribution tags like latest or beta. Access is granted through an access token in an Authorization header, and a granular token can be limited to read-only or read-and-write on specific packages, scopes, and organizations, while public reads need no token at all. The registry is largely unversioned, and it can push a change event to a webhook when a watched package or scope is updated.
How an app or AI agent connects to npm determines what it can reach. Most calls go to the registry, with separate hosts for download statistics and webhooks, and a Bearer token decides what each route can read or write.
The registry API answers at https://registry.npmjs.org. Most calls are path-based reads and writes against package documents, with no version header to pin. It is what the npm command-line tool itself calls.
The download statistics API answers at https://api.npmjs.org/downloads. It serves public total and per-day counts per package and needs no token.
Webhooks fire when a watched package or scope changes and post the event to a receiver URL. Each delivery carries an x-npm-signature header, computed from the hook's shared secret, so the receiver can confirm it came from npm.
Trusted publishing lets a CI job publish without a long-lived token, exchanging a short-lived OpenID Connect credential for publish access. It supports GitHub Actions and GitLab CI/CD.
A granular access token sets read-only or read-and-write access and can be limited to chosen packages, scopes, and organizations, with an expiry of up to 90 days and optional IP allow-lists. As of November 2025 it is the only supported token type, and a token with write access enforces two-factor authentication by default. It is the least-privilege choice for connecting to npm.
Trusted publishing exchanges a short-lived OpenID Connect credential from GitHub Actions or GitLab CI for publish access, so no long-lived token is stored. npm promotes it as the safer way to publish from automation.
Classic tokens came in read-only, publish, and automation types, but with coarse account-wide reach rather than per-package limits. New classic tokens can no longer be created, and npm revoked existing ones in November 2025.
The npm Registry API is split into areas an agent can act on, such as package metadata, search, publishing, distribution tags, and organization membership. Each area has its own methods and its own permissions, and writes change what every npm user installs.
Read a package's full metadata document, read a single version, and read the registry's own status.
Search the registry for packages by text, with weighting for quality, popularity, and maintenance.
Publish a new package version, deprecate a version, and unpublish a version.
List the tags on a package, point a tag such as latest or beta at a version, and remove a tag.
Read total and per-day download counts for one or many packages over a period.
Read the authenticated profile and list, create, or revoke access tokens.
Read who can reach a package, read its visibility, and grant or revoke team access to it.
List and change organization members and teams, and the packages a team can reach.
Look up known security advisories for a set of packages and version ranges.
List, create, update, and remove webhooks that fire when a package or scope changes.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Package metadataRead a package's full metadata document, read a single version, and read the registry's own status.3 | ||||||
| GET | /{package} | Get a package's full metadata document, including every version, dist-tags, and details. | read | read | Current | |
Public packages return without a token. A smaller install-oriented document is returned when the Accept header is application/vnd.npm.install-v1+json, since the full document can exceed 10MB for a package with many versions. A granular access token needs at least read access to a private package. Acts onpackage Permission (capability) readVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{package}/{version} | Get the metadata for a single package version, or use latest for the current one. | read | read | Current | |
Public versions return without a token. A granular access token needs at least read access to a private package. Acts onpackage version Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | / | Get registry status, including document counts and the latest update sequence. | read | — | Current | |
No token required. Acts onregistry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch the registry for packages by text, with weighting for quality, popularity, and maintenance.1 | ||||||
| GET | /-/v1/search | Search the registry for packages by text, returning matching package objects, a total, and a query time. | read | — | Current | |
Takes text, size, and from for paging, plus quality, popularity, and maintenance weights between 0 and 1 that tune the ranking. No token required for public results. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PublishingPublish a new package version, deprecate a version, and unpublish a version.3 | ||||||
| PUT | /{package} | Publish a new version of a package by sending its metadata document and the tarball attachment. | write | publish | Current | |
The body is a packument with name, dist-tags, versions, access, and the tarball in _attachments. Needs a token with read and write to the package or scope; trusted publishing through GitHub Actions or GitLab CI can supply a short-lived credential instead of a long-lived token. Acts onpackage version Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /{package} | Deprecate a version by updating the package document with a deprecation message, warning anyone who installs it. | write | publish | Current | |
Sent as an update to the package document with a deprecated field, not a separate path. Leaves the version installable, unlike unpublishing. Needs read and write to the package. Acts onpackage version Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{package}/-rev/{rev} | Unpublish a version, removing it and its tarball from the registry. | write | publish | Current | |
npm recommends deprecating rather than unpublishing, since removing a public version can break anything that depends on it. Unpublishing a public package is restricted by npm's unpublish policy, generally to within 72 hours of publishing. Needs read and write to the package. Acts onpackage version Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Distribution tagsList the tags on a package, point a tag such as latest or beta at a version, and remove a tag.3 | ||||||
| GET | /-/package/{package}/dist-tags | List the distribution tags on a package and the version each one points at. | read | read | Current | |
Distribution tags are human-readable labels, such as latest, beta, or next, that map to a version. Listing needs read access to a private package. Acts ondist-tag Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /-/package/{package}/dist-tags/{tag} | Point a distribution tag, such as latest or beta, at a specific version. | write | publish | Current | |
Moving the latest tag changes the version npm installs by default for everyone. Needs read and write to the package. Acts ondist-tag Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /-/package/{package}/dist-tags/{tag} | Remove a distribution tag from a package. | write | publish | Current | |
The latest tag cannot be removed. Needs read and write to the package. Acts ondist-tag Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Download countsRead total and per-day download counts for one or many packages over a period.2 | ||||||
| GET | /downloads/point/{period}/{package} | Get the total download count for a package over a period, such as last-day, last-week, or last-month. | read | — | Current | |
Served from api.npmjs.org, not the registry host. Periods are last-day, last-week, last-month, last-year, or a YYYY-MM-DD:YYYY-MM-DD range. Up to 128 comma-separated packages can be requested at once, except scoped packages. No token required. Acts ondownload stat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /downloads/range/{period}/{package} | Get a per-day breakdown of download counts for a package across a period. | read | — | Current | |
Served from api.npmjs.org. Standard queries reach back at most 18 months, with data from 10 January 2015 onward. No token required. Acts ondownload stat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account & tokensRead the authenticated profile and list, create, or revoke access tokens.4 | ||||||
| GET | /-/npm/v1/user | Get the authenticated user's profile, including name, email, and account details. | read | read | Current | |
Returns the profile object for the token's owner, or 401 when unauthenticated. Any valid token works. Acts onuser Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /-/npm/v1/tokens | List the access tokens on the authenticated account. | read | read | Current | |
Returns token metadata, never the secret values. Needs an authenticated token. Acts ontoken Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /-/npm/v1/tokens | Create a new access token for the authenticated account. | write | publish | Current | |
This endpoint creates legacy classic tokens, whose creation npm disabled across the website, CLI, and API in November 2025. Granular access tokens, the supported type, are created only on the npm website. Acts ontoken Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /-/npm/v1/tokens/token/{hash} | Revoke an access token by its hash. | write | publish | Current | |
Identified by the token's hash, not its secret value. Needs an authenticated token. Acts ontoken Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Package accessRead who can reach a package, read its visibility, and grant or revoke team access to it.3 | ||||||
| GET | /-/package/{package}/collaborators | Get the users who can reach a package and the access level each one has. | read | read | Current | |
Needs read access to the package or its scope. Acts onaccess grant Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /-/package/{package}/access | Set a package's access, such as making it public or restricted. | write | publish | Current | |
Changes who can install or publish the package. Needs read and write to the package or scope. Acts onaccess grant Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /-/team/{org}/{team}/package | Grant a team a permission on a package, such as read-only or read-write. | write | publish | Current | |
Needs organization-management access on the token, granted per organization. Acts onaccess grant Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Orgs & teamsList and change organization members and teams, and the packages a team can reach.4 | ||||||
| GET | /-/org/{org}/user | List the members of an organization and their roles. | read | read | Current | |
Needs organization access on the token. Acts onorg membership Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /-/org/{org}/user | Add a member to an organization or change their role. | write | publish | Current | |
A token granted organization access can manage organization settings, teams, and members, but cannot publish that organization's packages. Needs organization access. Acts onorg membership Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /-/org/{org}/user | Remove a member from an organization and its teams. | write | publish | Current | |
Needs organization access on the token. Acts onorg membership Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /-/org/{org}/team | List the teams in an organization. | read | read | Current | |
Needs organization access on the token. Acts onteam Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Security advisoriesLook up known security advisories for a set of packages and version ranges.1 | ||||||
| POST | /-/npm/v1/security/advisories/bulk | Look up known security advisories for a list of packages and version ranges. | read | — | Current | |
Takes a body of package names mapped to version arrays and returns the advisories that match. This is the data behind npm audit. Acts onadvisory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, create, update, and remove webhooks that fire when a package or scope changes.5 | ||||||
| GET | /v1/hooks | List the webhooks set up for the authenticated user. | read | read | Current | |
Served from the hooks host. Needs an authenticated token. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/hooks/hook | Create a webhook that fires when a package, scope, or maintainer's packages change. | write | publish | Current | |
A hook watches a specific package, a user scope, an organization scope, or all packages a maintainer owns. Deliveries carry an x-npm-signature header so the receiver can confirm they came from npm. Needs an authenticated token. Acts onwebhook Permission (capability) publishVersionAvailable since the API’s base version Webhook event package-changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/hooks/hook/{id} | Get a single webhook by its id. | read | read | Current | |
Needs an authenticated token. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/hooks/hook/{id} | Update a webhook by its id. | write | publish | Current | |
Needs an authenticated token. Acts onwebhook Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/hooks/hook/{id} | Remove a webhook by its id. | write | publish | Current | |
Needs an authenticated token. Acts onwebhook Permission (capability) publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
npm can notify an app or AI agent when a package or scope changes, instead of the app repeatedly asking. npm posts the event payload to a registered webhook URL, signed so the receiver can confirm it came from npm.
| Event | What it signals | Triggered by |
|---|---|---|
package:change | Fires when a watched package changes, such as a new version being published, a dist-tag moving, or a version being deprecated or unpublished. A hook can watch a single package, a user scope, an organization scope, or all packages a maintainer owns. | /{package}/{package}/{package}/-rev/{rev}/-/package/{package}/dist-tags/{tag}/-/package/{package}/dist-tags/{tag}/v1/hooks/hook |
npm limits how fast an app or AI agent can call the registry. Anonymous callers are held to a lower rate than authenticated ones, and going over returns a 429 response that says to slow down and retry.
npm rate-limits all registry APIs and returns HTTP 429 when a caller exceeds the limit. Anonymous requests are held to a lower rate than authenticated ones, so sending a token raises the ceiling. npm does not publish exact per-minute numbers; its acceptable-use guidance treats up to about five million registry requests per month as reasonable, and npm contacts organizations that consistently go beyond that. A client should handle 429 by backing off and retrying.
Search paginates through the size and from query parameters on /-/v1/search, where size sets how many results to return and from is the offset into the result set. Package metadata is returned as one document per package rather than a paged list, so reading a popular package means downloading its full version history in a single response unless the abbreviated install format is requested.
Requests and responses are JSON, except publishing, which sends the package tarball as a base64 attachment inside the package document. A full metadata document can exceed 10MB uncompressed for a package with many versions, which is why the abbreviated install format exists. Download-count bulk queries accept up to 128 comma-separated packages per request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or the token is invalid or expired. | Send a valid token in the Authorization Bearer header. |
| 403 | Forbidden | The token is valid but lacks the permission for the action, such as publishing to a package or scope it cannot write. | Grant the token read-and-write access to the package or scope, then retry. |
| 404 | Not Found | The package or version does not exist, or a private package is hidden from a token that cannot see it. | Confirm the package name and version, and that the token has access to a private package. |
| 429 | Too Many Requests | The request rate limit was exceeded. Anonymous callers are limited more tightly than authenticated ones. | Slow down and retry after a delay; authenticating raises the allowed rate. |
The npm registry is largely unversioned and path-based, with most methods served from a single, continuously updated surface. The search and account areas carry their own path prefixes, and notable changes ship through npm's dated changelog rather than a version header.
The npm registry has no dated API version to pin. Most package operations are served from a single, continuously updated surface, with the search and account areas under their own path prefixes. Notable changes are announced through npm's dated changelog rather than a version header, so an integration tracks behavior over time rather than pinning a version.
npm disabled creation of classic tokens across the website, command-line tool, and API, and revoked existing classic tokens on 19 November 2025. New tokens with write access now enforce two-factor authentication by default, and existing granular tokens with write access were capped at a 90-day maximum lifetime. It was announced on Wednesday 5 November 2025.
npm announced a rollout that shortened granular token lifetimes, began retiring classic tokens, limited two-factor setup options, and promoted trusted publishing. Granular tokens moved to a default 7-day expiry, down from 30, and a 90-day maximum, down from unlimited. It was announced on Monday 29 September 2025.
There is no version header to pin; an integration tracks behavior changes through the npm changelog.
npm changelog ↗Bollard AI sits between a team's AI agents and the npm registry. Grant each agent exactly the access it needs, read or write, package by package, and every call is checked and logged.