Netcracker Versions API

openapi: 3.2.0
info:
  title: APIHUB Registry – External Versions API
  description: 'Public-facing API contract for APIHUB. This API is intended for external and integration clients and covers package/catalog operations, publication workflows, search, user/profile actions, and selected administration capabilities secured by APIHUB authentication schemes.

    '
  contact:
    name: Netcracker Opensource Group
    email: opensourcegroup@netcracker.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.1'
  x-api-kind: BWC
servers:
- url: https://{apihub}.qubership.org
  description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
  variables:
    apihub:
      description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
      enum:
      - apihub
      - dev.apihub
      - staging.apihub
      default: apihub
security:
- BearerAuth: []
- CookieAuth: []
- api-key: []
- PersonalAccessToken: []
tags:
- name: Versions
  description: Published package versions API.
paths:
  /api/v3/packages/{packageId}/versions:
    parameters:
    - $ref: '#/components/parameters/packageId'
    get:
      tags:
      - Versions
      summary: Get package versions list
      description: Get the published package's versions list.
      operationId: getPackagesIdVersionsV3
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - name: textFilter
        in: query
        description: Filter by version name|labels.
        schema:
          type: string
      - name: status
        in: query
        description: Filter versions by status (start with match)
        required: false
        schema:
          type: string
          enum:
          - draft
          - release
          - archived
      - name: checkRevisions
        in: query
        description: 'Flag, if to search in the previous versions revisions.

          * if several revisions were found, return only the maximum found value.

          * if false - return the last published revision.

          '
        schema:
          type: boolean
          default: false
      - name: versionLabel
        in: query
        description: 'Filter the package versions by label, exact match.

          * if the checkRevisions: false - search in the last published revision.

          * if the checkRevisions: true - search in all revisions (backward order).

          '
        schema:
          type: string
          example: app.kubernetes.io/version:release-2022.4-20230228.094427-171
      - name: sortBy
        in: query
        description: Sort versions by version name or creation date
        schema:
          type: string
          enum:
          - version
          - createdAt
          default: version
      - name: sortOrder
        in: query
        description: Sorting order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: Whole package versions list with paging.
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PackageVersion'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/versions/{version}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    patch:
      tags:
      - Versions
      summary: Update package version
      description: 'Update package version.

        * If the parameter is not transmitted in request - its value stays unchanged.

        * The empty parameter value in request sets the empty value in database.

        * The array of labels will be fully replaced as-it-send, no JSON-Patch approach for arrays is applicable.

        '
      operationId: patchPackagesIdVersionsIdV2
      parameters:
      - $ref: '#/components/parameters/version'
      requestBody:
        description: Version update params
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/VersionStatusEnum'
                versionLabels:
                  description: List of version labels.
                  type: array
                  items:
                    type: string
                  example:
                  - app.kubernetes.io/part-of:CloudQSS-CPQBE
                  - app.kubernetes.io/version:release-candidate-20230410.152115-2782
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersionContent'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
                VersionStatusChangePreviousVersionNotRelease:
                  $ref: '#/components/examples/VersionStatusChangePreviousVersionNotRelease'
                VersionReferencedAsPreviousByRelease:
                  $ref: '#/components/examples/VersionReferencedAsPreviousByRelease'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      tags:
      - Versions
      summary: Delete package version
      description: 'Delete the package''s version.

        If the version was placed as a "defaultReleaseVersion" on a package, it will be cleared on this package (without the previous version restore).

        '
      operationId: deletePackagesIdVersionsId
      parameters:
      - $ref: '#/components/parameters/version'
      responses:
        '204':
          description: No content
          content: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                VersionReferencedByDashboard:
                  $ref: '#/components/examples/VersionReferencedByDashboard'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    get:
      tags:
      - Versions
      summary: Get package version content
      description: Get the published package's version content. Returns all content objects and folders.
      operationId: getPackagesIdVersionsIdV4
      parameters:
      - name: version
        in: path
        description: 'Package version.

          The mask <version>@<revision> may be used for search in a specific revision.

          '
        required: true
        schema:
          type: string
          example: 22.3@3
      - name: includeSummary
        in: query
        description: Show/hide the summary info about changes and operations.
        schema:
          type: boolean
          default: false
      - name: includeOperations
        in: query
        description: Show/hide the version's operations list.
        schema:
          type: boolean
          default: false
      - name: includeGroups
        in: query
        description: Flag to define whether to return list of groups of current version or not.
        schema:
          type: boolean
          default: false
      - name: sortBy
        in: query
        description: Sort versions by version name or creation date
        schema:
          type: string
          enum:
          - version
          - createdAt
          default: version
      - name: sortOrder
        in: query
        description: Sorting order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PackageVersionContent'
                - type: object
                  properties:
                    operationTypes:
                      type: array
                      items:
                        type: object
                        properties:
                          apiType:
                            $ref: '#/components/schemas/ApiType'
                          changesSummary:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of declarative changes in the version.
                          numberOfImpactedOperations:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of operations impacted by each severety type.
                          operationsCount:
                            type: number
                          deprecatedCount:
                            type: number
                          noBwcOperationsCount:
                            type: number
                            description: Number of no-BWC operations.
                          internalAudienceOperationsCount:
                            type: number
                            description: Number of operations with apiAudience = internal
                          unknownAudienceOperationsCount:
                            type: number
                            description: Number of operations with apiAudience = unknown
                          apiAudienceTransitions:
                            type: array
                            description: Shows transitions of operations' apiAudience value (compared to the previous release version) and number of operations in which this transition occurred. The array contains only records of transitions that actually occurred in operations.
                            items:
                              type: object
                              properties:
                                currentAudience:
                                  type: string
                                  description: Current apiAudience value (currentAudience must not be equal to previousAudience)
                                  enum:
                                  - internal
                                  - external
                                  - unknown
                                previousAudience:
                                  type: string
                                  description: Previous apiAudience value
                                  enum:
                                  - internal
                                  - external
                                  - unknown
                                operationsCount:
                                  type: number
                                  description: Number of operations in which the apiAudience was changed from previousAudience to currentAudience
                    contractsSummary:
                      $ref: '#/components/schemas/VersionContractsSummary'
                - type: object
                  properties:
                    operationGroups:
                      type: array
                      description: 'List of groups.

                        '
                      items:
                        allOf:
                        - $ref: '#/components/schemas/CreateOperationGroup'
                        - type: object
                          required:
                          - operationsCount
                          properties:
                            operationsCount:
                              type: number
                              description: Number of operations in operation group
                            ghostOperationsCount:
                              type: number
                              description: Number of ghost operations in operation group
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v4/packages/{packageId}/versions/{version}/{apiType}/changes:
    get:
      tags:
      - Versions
      summary: Get list of changed operations
      description: 'Get changes between two compared package versions with details by operations.\

        The result list depends on the API type.

        '
      operationId: getPackagesIdVersionsIdApiTypeChangesV4
      parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/apiAudience'
      - $ref: '#/components/parameters/asyncapiChannel'
      - $ref: '#/components/parameters/asyncapiProtocol'
      - $ref: '#/components/parameters/severity'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      - name: version
        in: path
        description: 'Package version.

          The mask <version>@<revision> may be used for search in a specific revision.

          '
        required: true
        schema:
          type: string
          example: 2022.3@3
      - name: refPackageId
        description: Filter by package id of ref package and previous ref package.
        in: query
        schema:
          type: string
      - name: apiKind
        description: Filter by api kind
        in: query
        schema:
          type: string
          enum:
          - bwc
          - no-bwc
          - experimental
      - name: documentSlug
        in: query
        description: Document unique string identifier
        schema:
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
      - name: tag
        in: query
        schema:
          type: string
        description: 'A full match is required.\

          Multiple tags separated by comma can be specified.

          '
      - name: emptyTag
        in: query
        description: 'Flag, filtering the operations without tags at all.

          In response will be returned the list of operations, on what the tag is not filled in.

          This attribute has a higher priority than the **tag**. In case, then **emptyTag: true**, it will override the **tag** filter.

          '
        schema:
          type: boolean
          default: false
      - name: group
        in: query
        description: 'Name of the group for filtering.\

          The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

          Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

          '
        schema:
          type: string
          example: v1
      - name: emptyGroup
        in: query
        description: 'Flag for filtering operations without a group.\

          The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

          Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

          '
        schema:
          type: boolean
          default: false
      - name: textFilter
        in: query
        description: 'Filter by operation''s title/path/method.

          For AsyncAPI: searches by message title(or messageId), channel title(or channelId) or operation action.

          '
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - operations
                properties:
                  previousVersion:
                    description: Name of the previous published version. The <version>@<revision> mask is used to return the revision number.
                    type: string
                    example: 2022.2@5
                  previousVersionPackageId:
                    description: Previous release version package id.
                    type: string
                    example: QS.CloudQSS.CPQ.Q-TMF
                  operations:
                    type: array
                    items:
                      allOf:
                      - oneOf:
                        - title: RestOperation
                          type: object
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/RestOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/RestOperationInfoFromDifferentVersions'
                        - title: GraphQLOperation
                          type: object
                          required:
                          - type
                          - method
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/GqlOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/GqlOperationInfoFromDifferentVersions'
                        - title: AsyncAPIOperation
                          description: AsyncAPI 3.0 operation change entry. Type-specific fields (action, channel, protocol) are inside previousOperation/currentOperation.
                          type: object
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/AsyncAPIOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/AsyncAPIOperationInfoFromDifferentVersions'
                      - type: object
                        required:
                        - changeSummary
                        - comparisonInternalDocumentId
                        properties:
                          changeSummary:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of declarative changes in one specific operation.
                          comparisonInternalDocumentId:
                            description: 'Unique string identifier of the internal merged document, where diffs between operation and previous operation are present. Corresponds to `id` field for the document in `comparison-internal-documents.json`

                              '
                            type: string
                            pattern: ^[a-z0-9-]
                            example: qitmf-v5-11-qitmf-v5-12-merged-json
                  packages:
                    $ref: '#/components/schemas/PackagesMap'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/versions/{version}/sources:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: version
      in: path
      description: Package version. The mask <version>@<revision> may be used to get resouces of the specific revision. If the @revision is not provided, the latest version's revision will be used.
      required: true
      schema:
        type: string
        example: '2022.3'
    get:
      tags:
      - Versions
      summary: Export sources of package version
      description: 'Export sources of package version as a zip archive.

        '
      operationId: getPackagesIdVersionsIdSources
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: ZIP file with pacakge version sources to download
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
                FileNotFound:
                  $ref: '#/components/examples/FileNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/versions/{version}/config:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: version
      in: path
      description: Package version. The mask <version>@<revision> may be used to get resouces of the specific revision. If the @revision is not provided, the latest version's revision will be used.
      required: true
      schema:
        type: string
        example: '2022.3'
    get:
      tags:
      - Versions
      summary: Get package version config
      description: 'Get content of package version config

        '
      operationId: getPackagesIdVersionsIdConfig
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
                FileNotFound:
                  $ref: '#/components/examples/FileNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}/{apiType}/build/groups/{groupName}/buildType/{buildType}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - name: apiType
      description: Type of the API.
      in: path
      required: true
      schema:
        type: string
        enum:
        - rest
    - name: buildType
      description: 'Type of the build process for OpeanAPI specification tranformation. Available options are:

        - **reducedSourceSpecifications** - proccess that finds source specifications for all operations from operation group and removes from these specifications operations other than those that are included into operation group.

        - **mergedSpecification** - process the merges all operations from an operation group into one specification.

        '
      in: path
      required: true
      schema:
        type: string
        enum:
        - reducedSourceSpecifications
        - mergedSpecification
    - name: groupName
      in: path
      required: true
      description: Name of the operation group
      schema:
        type: string
    post:
      deprecated: true
      x-deprecation-reason: POST /api/v1/export shall be used instead of the current operation.
      tags:
      - Versions
      summary: Async document transformation
      description: 'Async task for document transformation. Document transformation is required for exporting operations group.

        * **200 Documents transformation completed successfully** if documents were already transformed.


        * **202 Accepted** will be returned after starting process for documents transformation.

        '
      operationId: postGenerateDocumentV3
      parameters:
      - name: clientBuild
        in: query
        description: Client-side package build will be used.
        required: false
        schema:
          type: boolean
          default: false
      - name: builderId
        in: query
        required: false
        description: Builder identifier. **Required** if clientBuild=true.
        schema:
          type: string
      - name: reCalculate
        in: query
        description: 'Flag for the force document re-calculation.

          May be used after the previous API call with **error** status.

          '
        schema:
          type: boolean
          default: false
      - name: format
        in: query
   

# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netcracker/refs/heads/main/openapi/netcracker-versions-api-openapi.yml