openapi: 3.1.0
info:
  title: npm Registry API
  description: >-
    The npm Registry API provides programmatic access to the npm package
    registry, the largest software registry in the world hosting over two
    million JavaScript packages. Developers can query package metadata,
    download tarballs, search for packages, and retrieve version-specific
    information. The API follows CouchDB-based conventions and serves
    package manifests in JSON format, enabling tools and services to
    integrate with the npm ecosystem for dependency resolution, package
    discovery, and automated workflows.
  version: '1.0.0'
  contact:
    name: npm Support
    url: https://www.npmjs.com/support
  termsOfService: https://docs.npmjs.com/policies/terms
externalDocs:
  description: npm Registry API Documentation
  url: https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
servers:
  - url: https://registry.npmjs.org
    description: npm Public Registry
tags:
  - name: Downloads
    description: >-
      Package tarball downloads.
  - name: Packages
    description: >-
      Package metadata retrieval, including full packuments and
      version-specific documents.
  - name: Registry
    description: >-
      Registry metadata and status information.
  - name: Search
    description: >-
      Full-text search across the npm registry with weighted scoring.
paths:
  /:
    get:
      operationId: getRegistryMetadata
      summary: Get registry metadata
      description: >-
        Returns metadata about the npm registry, including document counts,
        storage sizes, and instance information. This endpoint follows the
        CouchDB database information convention.
      tags:
        - Registry
      responses:
        '200':
          description: Registry metadata retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryMetadata'
  /{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'
  /{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'
  /-/v1/search:
    get:
      operationId: searchPackages
      summary: Search packages
      description: >-
        Performs a full-text search across the npm registry. Results can be
        weighted by quality, popularity, and maintenance scores. Supports
        special search qualifiers such as author, maintainer, scope, and
        keywords filters. Qualifiers like not:unstable, not:insecure,
        is:unstable, and boost-exact can be included in the text parameter.
      tags:
        - Search
      parameters:
        - name: text
          in: query
          description: >-
            Full-text search query. Supports special qualifiers such as
            author:username, maintainer:username, scope:scopename,
            keywords:keyword, not:unstable, not:insecure, is:unstable,
            is:insecure, and boost-exact:true.
          required: true
          schema:
            type: string
        - name: size
          in: query
          description: >-
            Number of results to return. Maximum value is 250.
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 250
        - name: from
          in: query
          description: >-
            Offset for pagination, indicating the starting position in the
            result set.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: quality
          in: query
          description: >-
            Weighting for the quality score component of search results,
            between 0 and 1.
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: popularity
          in: query
          description: >-
            Weighting for the popularity score component of search results,
            between 0 and 1.
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: maintenance
          in: query
          description: >-
            Weighting for the maintenance score component of search results,
            between 0 and 1.
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 1
      responses:
        '200':
          description: Search results returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
  /{package}/-/{tarball}:
    get:
      operationId: downloadPackageTarball
      summary: Download a package tarball
      description: >-
        Downloads the tarball archive for a specific version of a package.
        The tarball filename is typically in the format
        {package}-{version}.tgz. This endpoint is used by the npm CLI
        during package installation.
      tags:
        - Downloads
      parameters:
        - $ref: '#/components/parameters/packageName'
        - name: tarball
          in: path
          description: >-
            The tarball filename, typically in the format
            {package}-{version}.tgz.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tarball file returned successfully.
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '404':
          description: Tarball not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    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
    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
  schemas:
    RegistryMetadata:
      type: object
      description: >-
        Metadata about the npm registry instance, following CouchDB
        database information conventions.
      properties:
        db_name:
          type: string
          description: >-
            The name of the database, typically "registry".
        doc_count:
          type: integer
          description: >-
            The total number of documents in the registry.
        doc_del_count:
          type: integer
          description: >-
            The total number of deleted documents.
        update_seq:
          type: integer
          description: >-
            The current update sequence number.
        purge_seq:
          type: integer
          description: >-
            The current purge sequence number.
        compact_running:
          type: boolean
          description: >-
            Whether a database compaction is currently running.
        disk_size:
          type: integer
          description: >-
            Total disk size in bytes.
        data_size:
          type: integer
          description: >-
            Actual data size in bytes.
        instance_start_time:
          type: string
          description: >-
            Timestamp of when this registry instance started.
        disk_format_version:
          type: integer
          description: >-
            The version of the on-disk storage format.
        committed_update_seq:
          type: integer
          description: >-
            The last committed update sequence number.
    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.
    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'
    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.
    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.
    SearchResults:
      type: object
      description: >-
        Search results from the npm registry search endpoint.
      properties:
        objects:
          type: array
          description: >-
            List of search result objects.
          items:
            $ref: '#/components/schemas/SearchResultItem'
        total:
          type: integer
          description: >-
            The total number of matching results.
        time:
          type: string
          description: >-
            Timestamp of when the search was performed.
    SearchResultItem:
      type: object
      description: >-
        A single search result item containing package metadata and
        scoring information.
      properties:
        package:
          type: object
          description: >-
            Summary package metadata.
          properties:
            name:
              type: string
              description: >-
                The package name.
            scope:
              type: string
              description: >-
                The package scope, or "unscoped" if none.
            version:
              type: string
              description: >-
                The latest version of the package.
            description:
              type: string
              description: >-
                A short description of the package.
            keywords:
              type: array
              description: >-
                Keywords associated with the package.
              items:
                type: string
            date:
              type: string
              format: date-time
              description: >-
                The publication date of the latest version.
            links:
              type: object
              description: >-
                Links to related resources such as npm page, homepage,
                repository, and bugs.
              additionalProperties:
                type: string
            author:
              $ref: '#/components/schemas/Person'
            publisher:
              $ref: '#/components/schemas/Person'
            maintainers:
              type: array
              description: >-
                List of package maintainers.
              items:
                $ref: '#/components/schemas/Person'
        score:
          type: object
          description: >-
            Scoring breakdown for the package.
          properties:
            final:
              type: number
              description: >-
                The final combined score.
            detail:
              type: object
              description: >-
                Detailed score breakdown.
              properties:
                quality:
                  type: number
                  description: >-
                    The quality score component.
                popularity:
                  type: number
                  description: >-
                    The popularity score component.
                maintenance:
                  type: number
                  description: >-
                    The maintenance score component.
        searchScore:
          type: number
          description: >-
            The search relevance score for this result.
    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.