npm Packages API

openapi: 3.2.0
info:
  title: Npm Packages API
  version: 1.0.0
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Packages across 3 of this provider''s published API definitions: npm-registry-reference-openapi.json, npm-registry-reference-openapi.yml, npm-packages-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://registry.npmjs.org
tags:
- name: Packages
  x-displayName: Packages
  description: Package metadata and lifecycle endpoints.
paths:
  /-/package/{package-name}/version/{version}/status:
    get:
      tags:
      - Packages
      summary: Get the lifecycle status of an exact package version
      description: 'Returns the current lifecycle status of an exact package version. The response may represent validation progress, manual approval, or publication without exposing validation-system details.


        The authenticated user must have publish access to the package. A package authorization failure is returned as not found.'
      operationId: getPackageVersionStatus
      parameters:
      - name: package-name
        in: path
        required: true
        schema:
          type: string
        description: The exact package name. Scoped names must be URL-encoded with the slash escaped.
      - name: version
        in: path
        required: true
        schema:
          type: string
        description: The exact semantic version.
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          pattern: ^Bearer .+
        description: An npm access token or granular access token for a package maintainer.
      security:
      - npmAccessToken: []
      - granularAccessToken: []
      responses:
        '200':
          description: The current lifecycle status of the package version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersionStatus'
              examples:
                validationInProgress:
                  summary: The version is still being processed
                  value:
                    packageName: '@npmcli/example-package'
                    version: 1.2.3
                    status: validating
        '400':
          $ref: '#/components/responses/PackageVersionStatusBadRequest'
        '401':
          $ref: '#/components/responses/PackageVersionStatusUnauthorized'
        '403':
          $ref: '#/components/responses/PackageVersionStatusForbidden'
        '404':
          $ref: '#/components/responses/PackageVersionStatusNotFound'
        '429':
          $ref: '#/components/responses/PackageVersionStatusTooManyRequests'
        '500':
          $ref: '#/components/responses/PackageVersionStatusInternalServerError'
        '503':
          $ref: '#/components/responses/PackageVersionStatusUnavailable'
    servers:
    - url: https://registry.npmjs.org
  /{package}:
    get:
      operationId: getPackageDocument
      summary: Get a package document (packument)
      description: Retrieves the full package document (packument) for a given package name. The packument includes all published versions, dist-tags, maintainers, repository information, and README content. For scoped packages, the package name should be URL-encoded (e.g., @scope%2Fpackage).
      tags:
      - Packages
      parameters:
      - $ref: '#/components/parameters/packageName'
      responses:
        '200':
          description: Package document retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageDocument'
        '404':
          description: Package not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://registry.npmjs.org
      description: npm Public Registry
  /{package}/{version}:
    get:
      operationId: getPackageVersion
      summary: Get a specific package version
      description: Retrieves metadata for a specific version of a package. The version can be a valid semver string or the literal string "latest" to retrieve the version pointed to by the latest dist-tag. Returns the version-specific manifest including dependencies, scripts, and distribution information.
      tags:
      - Packages
      parameters:
      - $ref: '#/components/parameters/packageName'
      - $ref: '#/components/parameters/packageVersion'
      responses:
        '200':
          description: Package version metadata retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersion'
        '404':
          description: Package or version not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://registry.npmjs.org
      description: npm Public Registry
components:
  responses:
    PackageVersionStatusUnauthorized:
      description: Authentication is missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusUnavailable:
      description: The package-version status service is temporarily unavailable.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusInternalServerError:
      description: An internal error occurred.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusBadRequest:
      description: 'The package name or the version is not valid. The version must be an exact semver version, so a range such as `^1.0.0` is rejected. This is checked before authentication, so it is returned even when no credential is supplied.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusTooManyRequests:
      description: The request was rate limited.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusForbidden:
      description: 'Package version status is not enabled for this package. This is the rollout gate only. Not having access to a package is reported as `404`, not here.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PackageVersionStatusNotFound:
      description: 'The package version does not exist, or the authenticated user cannot read it. These are deliberately indistinguishable so the response does not reveal whether a package the caller cannot see exists.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    PackageVersionStatus:
      type: object
      required:
      - packageName
      - version
      - status
      properties:
        packageName:
          type: string
          description: The exact package name.
        version:
          type: string
          description: The exact package version.
        status:
          type: string
          description: 'Where the version currently stands.


            `published` means it is live and installable. `validating` means it is still on its way and the caller should check again shortly. `staged` means it is waiting for a maintainer to approve it. `blocked` means it did not pass automated validation and cannot be installed. `deleted` means it was published and has since been removed.

            '
          enum:
          - published
          - validating
          - staged
          - blocked
          - deleted
    Error:
      type: object
      description: An error response from the registry.
      properties:
        error:
          type: string
          description: The error type or code.
        reason:
          type: string
          description: A human-readable explanation of the error.
    PackageDocument:
      type: object
      description: A full package document (packument) containing all metadata for a package, including every published version.
      properties:
        _id:
          type: string
          description: The package name, used as the document identifier.
        _rev:
          type: string
          description: The CouchDB document revision identifier.
        name:
          type: string
          description: The name of the package.
        description:
          type: string
          description: A short description of the package.
        dist-tags:
          type: object
          description: A mapping of distribution tags to version strings. The "latest" tag is always present.
          additionalProperties:
            type: string
        versions:
          type: object
          description: A mapping of version strings to version metadata objects.
          additionalProperties:
            $ref: '#/components/schemas/PackageVersion'
        time:
          type: object
          description: A mapping of version strings to ISO 8601 timestamps indicating when each version was published. Includes special keys "created" and "modified".
          additionalProperties:
            type: string
            format: date-time
        maintainers:
          type: array
          description: List of current package maintainers.
          items:
            $ref: '#/components/schemas/Person'
        author:
          $ref: '#/components/schemas/Person'
        repository:
          $ref: '#/components/schemas/Repository'
        readme:
          type: string
          description: The README content for the package, typically from the latest version.
        readmeFilename:
          type: string
          description: The filename of the README file.
        homepage:
          type: string
          format: uri
          description: The URL of the package homepage.
        keywords:
          type: array
          description: Keywords associated with the package for search discovery.
          items:
            type: string
        bugs:
          type: object
          description: Issue tracker information.
          properties:
            url:
              type: string
              format: uri
              description: URL of the issue tracker.
        license:
          type: string
          description: The SPDX license identifier for the package.
    Repository:
      type: object
      description: Source code repository information.
      properties:
        type:
          type: string
          description: The version control system type, typically "git".
        url:
          type: string
          description: The URL of the source code repository.
    Distribution:
      type: object
      description: Distribution metadata for a specific published version, including integrity hashes and tarball location.
      properties:
        shasum:
          type: string
          description: The SHA-1 checksum of the tarball.
        tarball:
          type: string
          format: uri
          description: The URL where the tarball can be downloaded.
        integrity:
          type: string
          description: The Subresource Integrity (SRI) hash of the tarball, typically using SHA-512.
        fileCount:
          type: integer
          description: The number of files in the tarball.
        unpackedSize:
          type: integer
          description: The total unpacked size of the tarball in bytes.
        signatures:
          type: array
          description: Cryptographic signatures for the package version.
          items:
            type: object
            properties:
              keyid:
                type: string
                description: The identifier of the signing key.
              sig:
                type: string
                description: The signature value.
    Person:
      type: object
      description: A person object representing a user, author, or maintainer.
      properties:
        name:
          type: string
          description: The display name of the person.
        email:
          type: string
          format: email
          description: The email address of the person.
        url:
          type: string
          format: uri
          description: The personal URL or website of the person.
    PackageVersion:
      type: object
      description: Metadata for a specific version of a package, including dependencies, scripts, and distribution information.
      properties:
        name:
          type: string
          description: The name of the package.
        version:
          type: string
          description: The semver version string.
        description:
          type: string
          description: A short description of the package.
        main:
          type: string
          description: The entry point module for the package.
        scripts:
          type: object
          description: A mapping of script names to shell commands.
          additionalProperties:
            type: string
        dependencies:
          type: object
          description: A mapping of package names to semver ranges for runtime dependencies.
          additionalProperties:
            type: string
        devDependencies:
          type: object
          description: A mapping of package names to semver ranges for development dependencies.
          additionalProperties:
            type: string
        peerDependencies:
          type: object
          description: A mapping of package names to semver ranges for peer dependencies.
          additionalProperties:
            type: string
        optionalDependencies:
          type: object
          description: A mapping of package names to semver ranges for optional dependencies.
          additionalProperties:
            type: string
        engines:
          type: object
          description: A mapping of runtime names to semver ranges specifying compatible environments.
          additionalProperties:
            type: string
        author:
          $ref: '#/components/schemas/Person'
        maintainers:
          type: array
          description: List of maintainers for this version.
          items:
            $ref: '#/components/schemas/Person'
        repository:
          $ref: '#/components/schemas/Repository'
        license:
          type: string
          description: The SPDX license identifier.
        keywords:
          type: array
          description: Keywords associated with this version.
          items:
            type: string
        dist:
          $ref: '#/components/schemas/Distribution'
        _npmVersion:
          type: string
          description: The version of npm used to publish this package version.
        _nodeVersion:
          type: string
          description: The version of Node.js used to publish this package version.
        _npmUser:
          $ref: '#/components/schemas/Person'
  parameters:
    packageVersion:
      name: version
      in: path
      description: A valid semver version string, or the literal string "latest" to resolve the current latest dist-tag.
      required: true
      schema:
        type: string
    packageName:
      name: package
      in: path
      description: The name of the package. For scoped packages, use URL encoding (e.g., @scope%2Fpackage).
      required: true
      schema:
        type: string
  securitySchemes:
    oidcIdToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OIDC id_token from a supported Identity Provider (IdP) such as GitHub Actions, GitLab CI, or CircleCI.

        The `aud` (audience) claim must be set to `npm:registry.npmjs.org`.


        **Supported Identity Providers:**

        - GitHub Actions

        - GitLab CI

        - CircleCI

        '
    npmSessionToken:
      type: http
      scheme: bearer
      description: 'Traditional npm session token created via `npm login`.

        These tokens are tied to a user account and inherit the user''s permissions.

        '
    npmAccessToken:
      type: http
      scheme: bearer
      description: 'Granular Access Token (GAT) with fine-grained permissions.

        These tokens can be scoped to specific packages and operations.


        GATs created with `bypass_2fa: true` cannot perform account,

        token, or org/team/package governance write operations — those

        requests are rejected with `403 Forbidden`. See the Authentication

        section above for the full list.

        '
    granularAccessToken:
      type: http
      scheme: bearer
      description: 'Granular Access Token (GAT) with fine-grained permissions.

        These tokens can be scoped to specific packages and operations.

        (Alias for npmAccessToken)


        GATs created with `bypass_2fa: true` cannot perform account,

        token, or org/team/package governance write operations — those

        requests are rejected with `403 Forbidden`.

        '
    oidcExchangeToken:
      type: http
      scheme: bearer
      description: 'Short-lived npm registry token obtained by exchanging an OIDC id_token

        via the `/oidc/token/exchange` endpoint. These tokens are package-scoped

        and have limited lifetime (typically 1 hour).

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: npm access token provided as a Bearer token.
externalDocs:
  description: npm Hooks Documentation
  url: https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm
x-refined-from:
- npm-registry-reference-openapi.json
- npm-registry-reference-openapi.yml
- npm-packages-api-openapi.yml