openapi: 3.0.3
info:
  title: Verdaccio npm Registry dist-tags publish API
  description: 'The Verdaccio npm Registry REST API implements the CommonJS Compliant Package Registry specification, providing endpoints to publish, retrieve, search, and delete npm packages. It supports JWT tokens and Basic Auth for authentication and mirrors the standard npm registry protocol so any npm, yarn, or pnpm client can interact with it without modification.

    '
  version: 6.0.0
  contact:
    name: Verdaccio Community
    url: https://discord.gg/7qWJxBf
  license:
    name: MIT
    url: https://github.com/verdaccio/verdaccio/blob/master/LICENSE
  x-api-id: verdaccio:verdaccio-npm-registry-api
servers:
- url: http://localhost:4873
  description: Default local Verdaccio instance
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: publish
  description: Publish, update, and unpublish packages
paths:
  /{package}:
    put:
      operationId: publishPackage
      summary: Publish a new package
      description: 'Publishes a new package or a new version of an existing package. The request body must include the package metadata and an `_attachments` property containing the base64-encoded tarball.

        '
      tags:
      - publish
      parameters:
      - $ref: '#/components/parameters/PackageName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '201':
          description: Package published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Package version already exists
  /{package}/-rev/{revision}:
    put:
      operationId: updatePackageRevision
      summary: Update package at a specific revision
      description: 'Used during unpublish to update the package manifest to a new revision, removing the specified version from metadata.

        '
      tags:
      - publish
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: revision
        in: path
        required: true
        schema:
          type: string
        description: CouchDB-style revision identifier (e.g. `14-abc123`)
        example: 14-5d500cfce92f90fd
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '201':
          description: Package revision updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /{package}/-/{filename}/-rev/{revision}:
    delete:
      operationId: deleteTarball
      summary: Delete a package tarball
      description: 'Deletes a specific tarball file. Called as the final step of the npm unpublish flow after the package manifest has been updated.

        '
      tags:
      - publish
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: Tarball filename (e.g. `package-1.0.0.tgz`)
        example: my-package-1.0.0.tgz
      - name: revision
        in: path
        required: true
        schema:
          type: string
        description: CouchDB-style revision identifier
        example: 16-e11c8db282b2d992
      responses:
        '201':
          description: Tarball deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Package or resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Authenticated user lacks permission for this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or credentials are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    PackageAttachment:
      type: object
      properties:
        content_type:
          type: string
          example: application/octet-stream
        data:
          type: string
          format: byte
          description: Base64-encoded tarball content
        length:
          type: integer
          description: Byte length of the unencoded tarball
    DistTagsMap:
      type: object
      additionalProperties:
        type: string
      description: Map of dist-tag names to version strings
      example:
        latest: 1.2.3
        next: 2.0.0-beta.1
        beta: 2.0.0-beta.1
    OkResponse:
      type: object
      properties:
        ok:
          type: string
          description: Human-readable success message
          example: package published
      required:
      - ok
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: package not found
      required:
      - error
    PublishRequest:
      type: object
      description: Package manifest payload used for publish and revision update operations
      properties:
        _id:
          type: string
          description: Package name used as document ID
          example: my-package
        name:
          type: string
          description: Package name
          example: my-package
        description:
          type: string
          description: Package description
        dist-tags:
          $ref: '#/components/schemas/DistTagsMap'
        versions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VersionManifest'
        _attachments:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PackageAttachment'
          description: Tarball attachments keyed by filename
      required:
      - name
      - versions
    VersionManifest:
      type: object
      description: Metadata for a single package version
      properties:
        name:
          type: string
          example: my-package
        version:
          type: string
          example: 1.0.0
        description:
          type: string
        main:
          type: string
          example: index.js
        scripts:
          type: object
          additionalProperties:
            type: string
        keywords:
          type: array
          items:
            type: string
        author:
          oneOf:
          - type: string
          - type: object
            properties:
              name:
                type: string
              email:
                type: string
              url:
                type: string
        license:
          type: string
          example: MIT
        dependencies:
          type: object
          additionalProperties:
            type: string
        devDependencies:
          type: object
          additionalProperties:
            type: string
        peerDependencies:
          type: object
          additionalProperties:
            type: string
        dist:
          type: object
          properties:
            tarball:
              type: string
              format: uri
              description: URL to download this version's tarball
              example: http://localhost:4873/my-package/-/my-package-1.0.0.tgz
            shasum:
              type: string
              description: SHA-1 checksum of the tarball
              example: da39a3ee5e6b4b0d3255bfef95601890afd80709
            integrity:
              type: string
              description: Subresource Integrity hash
              example: sha512-abc123==
        _id:
          type: string
          example: my-package@1.0.0
        _nodeVersion:
          type: string
          example: 20.11.0
        _npmVersion:
          type: string
          example: 10.2.4
  parameters:
    PackageName:
      name: package
      in: path
      required: true
      schema:
        type: string
      description: Package name (may be scoped, e.g. `@scope%2Fpackage`)
      example: lodash
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token issued by Verdaccio on login
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth with registry username and password