Verdaccio dist-tags API

openapi: 3.0.3
info:
  title: Verdaccio npm Registry dist-tags 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: dist-tags
  description: Manage dist-tags for packages
paths:
  /-/package/{package}/dist-tags:
    get:
      operationId: getDistTags
      summary: List all dist-tags for a package
      description: Returns a map of dist-tag names to version strings for the specified package.
      tags:
      - dist-tags
      parameters:
      - $ref: '#/components/parameters/PackagePathParam'
      responses:
        '200':
          description: Dist-tags map
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistTagsMap'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /-/package/{package}/dist-tags/{tag}:
    put:
      operationId: setDistTag
      summary: Set a dist-tag on a package
      description: Sets or updates a named dist-tag to point to the specified version string.
      tags:
      - dist-tags
      parameters:
      - $ref: '#/components/parameters/PackagePathParam'
      - $ref: '#/components/parameters/TagName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              description: Version string to associate with the tag
              example: 1.2.0
      responses:
        '201':
          description: Tag set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteDistTag
      summary: Delete a dist-tag from a package
      description: Removes a named dist-tag from the package.
      tags:
      - dist-tags
      parameters:
      - $ref: '#/components/parameters/PackagePathParam'
      - $ref: '#/components/parameters/TagName'
      responses:
        '201':
          description: Tag removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /{package}/{tag}:
    put:
      operationId: setDistTagShort
      summary: Set a dist-tag (shorthand route)
      description: Alternative shorthand route for setting a dist-tag, compatible with older npm clients.
      tags:
      - dist-tags
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - $ref: '#/components/parameters/TagName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              description: Version string to associate with the tag
              example: 1.2.0
      responses:
        '201':
          description: Tag set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    TagName:
      name: tag
      in: path
      required: true
      schema:
        type: string
      description: Dist-tag name (e.g. `latest`, `next`, `beta`)
      example: latest
    PackagePathParam:
      name: package
      in: path
      required: true
      schema:
        type: string
      description: Package name (may be scoped)
      example: lodash
    PackageName:
      name: package
      in: path
      required: true
      schema:
        type: string
      description: Package name (may be scoped, e.g. `@scope%2Fpackage`)
      example: lodash
  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:
    OkResponse:
      type: object
      properties:
        ok:
          type: string
          description: Human-readable success message
          example: package published
      required:
      - ok
    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
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: package not found
      required:
      - error
  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