openapi: 3.2.0
info:
  title: APIHUB Registry – External Publish 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: Publish
  description: Publish version API
paths:
  /api/v2/packages/{packageId}/publish:
    parameters:
    - $ref: '#/components/parameters/packageId'
    post:
      tags:
      - Publish
      summary: Publish package version via upload
      description: 'Publish package version via upload. Possible options:

        * **Client-side building** - client application marks, that the validation and build of the final specification will be outside the APIHUB backend.

        The final specifications will be stored using the POST /packages/{packageId}/publish/{publishId}/status API.

        The 202 response and the publish process Id will be returned in success.

        In case of the client session close, the build will be continued on the server-sde.

        * **Server-side building** - client application send all raw files-sources and starts the validation and build of the final specification in APIHUB backend.

        The 202 response and the publish process Id will be returned in success.

        * **No building** - only references publication. Files array in config and sources are empty. In this case the build process won''t be started.

        The 204 response will be returned in success.

        '
      operationId: postPackagesIdPublish
      parameters:
      - name: clientBuild
        in: query
        description: Client-side package build will be used. Should be used only for browser-based build process.
        required: false
        schema:
          type: boolean
          default: false
      - name: resolveRefs
        in: query
        required: false
        description: With resolveRefs=true all references will be resolved into a flat list. With resolveRefs=false it's expected that all references are already resolved.
        schema:
          type: boolean
          default: true
      - name: resolveConflicts
        in: query
        required: false
        description: 'In case when resolved refs list contains multiple versions of the same package:

          - if resolveConflicts=false - status 400 (Bad request). Conflicts should be resolved manually.

          - if resolveConflicts=true - conflicts will be resolved automatically, some refs will be marked as excluded'
        schema:
          type: boolean
          default: true
      requestBody:
        description: Publish params
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - config
              properties:
                sources:
                  type: string
                  description: 'Files for publish in one zip archive.

                    **Required**, if the files array is filled in the config.

                    '
                  format: binary
                config:
                  $ref: '#/components/schemas/BuildConfig'
                builderId:
                  type: string
                  description: Builder identifier. **Required** only if clientBuild=true. Used to bind the build to specific executor.
      responses:
        '202':
          description: Publish process started
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  title: serverBuild
                  properties:
                    publishId:
                      type: string
                      description: Publish process Id
                      format: uuid
                      example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
                - type: object
                  title: clientBuild
                  description: Returns final build config when clientBuild=true
                  properties:
                    publishId:
                      type: string
                      description: Publish process Id
                      format: uuid
                      example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
                    config:
                      $ref: '#/components/schemas/BuildConfig'
        '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
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
                PreviousVersionNotRelease:
                  $ref: '#/components/examples/PreviousVersionNotRelease'
                VersionReferencedAsPreviousByRelease:
                  $ref: '#/components/examples/VersionReferencedAsPreviousByRelease'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '403':
          description: Forbidden. Editor or admin rights for the package are required to publish version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/publish/{publishId}/status:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: publishId
      description: Publish Id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
      - Publish
      summary: Get publish process status
      description: Get publish process status.
      operationId: getPackagesIdPublishIdStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Publish process status.
                    type: string
                    enum:
                    - running
                    - error
                    - complete
                    - none
                  message:
                    description: The message for **error** status.
                    type: string
        '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: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/publish/withOperationsGroup:
    parameters:
    - $ref: '#/components/parameters/packageId'
    post:
      tags:
      - Publish
      summary: Start dashboard version publication from CSV file
      deprecated: true
      x-deprecation-reason: Use /api/v2/packages/{packageId}/publish/withOperationsGroup/{apiType} instead
      description: 'Start dashboard version publication from CSV file (value of ''packageId''

        path parameter must be an Id of dashboard).\


        In this process the system reads information from the input CSV file

        which contains list of services and their versions. Based on this info,

        the system searches for package release versions and publish dashboard

        version with references to the found package versions.\


        Also, CSV file contains info about REST API operations

        (method, path) of listed services, the system searches for operations

        from the included package versions and automatically creates operations

        group (manual group with rest api type) in published dashboard version

        with all found operations.

        '
      operationId: DashboardPublishWithOperationsGroup
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - csvFile
              - version
              - status
              - servicesWorkspaceId
              properties:
                csvFile:
                  description: "CSV file with information about\nservices and their operations:\n  * serviceName\n  * serviceVersion\n  * method\n  * path\n"
                  type: string
                  format: binary
                servicesWorkspaceId:
                  type: string
                  description: Id of the workspace in which the system will search for packages for the services specified in the CSV file.
                version:
                  description: Version name for publication in the dashboard.
                  type: string
                  example: '2022.3'
                previousVersion:
                  description: Name of the previous published version in the dashboard.
                  type: string
                  example: '2022.2'
                previousVersionPackageId:
                  description: packageId of the previous version. The parameter may be empty if the value is equal to the packageId.
                  type: string
                  example: NC.CloudBSS.CPQ.Q-TMF
                status:
                  $ref: '#/components/schemas/VersionStatusEnum'
                versionLabels:
                  description: List of version labels in dashboard version.
                  type: array
                  items:
                    type: string
                  example:
                  - part-of:CloudBSS-CPQBE
      responses:
        '202':
          description: Publish process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  publishId:
                    type: string
                    description: Publish process Id
                    format: uuid
                    example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
                PreviousVersionNotRelease:
                  $ref: '#/components/examples/PreviousVersionNotRelease'
                VersionReferencedAsPreviousByRelease:
                  $ref: '#/components/examples/VersionReferencedAsPreviousByRelease'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/publish/{publishId}/withOperationsGroup/status:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: publishId
      description: Publish Id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
      - Publish
      summary: Get dashboard version publication from CSV file status
      description: 'Get dashboard version publication from CSV file status.

        '
      operationId: getDashboardPublishWithOperationsGroupStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Publish process status.
                    type: string
                    enum:
                    - running
                    - error
                    - complete
                    - none
                  message:
                    description: "* The message for **error** status.\n* The message for **complete** status with the following\ninformation (if applicalbe):\n  * N services were not included into dashboard version.\n  * N operations were not included into \\<operation group name\\> operation group.\n  If all services and operations were included into dashboard and group, then message shall be empty.\n"
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/publish/{publishId}/withOperationsGroup/status/report:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: publishId
      description: Publish Id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
      - Publish
      summary: Get CSV report of dashboard version publication from CSV file
      description: 'CSV file with initial input information which is added with status and

        error messages for each row.

        '
      operationId: getDashboardPublishWithOperationsGroupStatusReport
      responses:
        '200':
          description: Success
          content:
            text/csv:
              schema:
                type: string
                format: binary
                description: CSV file which contains initial (input) content and supplemented with information about status and details info if any problems occured (package version was not found, operation was not found, insufficient information provided).
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/publish/withOperationsGroup/{apiType}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: apiType
      description: Type of the API. Only REST and GraphQL are supported for CSV publish.
      in: path
      required: true
      schema:
        type: string
        enum:
        - rest
        - graphql
    post:
      tags:
      - Publish
      summary: Start dashboard version publication from CSV file
      description: 'Start dashboard version publication from CSV file (value of ''packageId''

        path parameter must be an Id of dashboard).


        In this process the system reads information from the input CSV file

        which contains list of services and their versions. Based on this info,

        the system searches for package release versions (in the specified workspace) and publishes

        a dashboard version with references to the found package versions.


        Also, the CSV file contains info about operations

        of listed services, the system searches for operations

        from the included package versions and automatically creates an operations

        group (manual group with the specified api type) in the published dashboard version

        with all found operations.


        CSV file columns depend on the API type, all columns are mandatory:

        * **REST**: service, version, method, path

        * **GraphQL**: service, version, type, method

        '
      operationId: DashboardPublishWithOperationsGroupV2
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - csvFile
              - version
              - status
              - servicesWorkspaceId
              properties:
                csvFile:
                  description: 'CSV file with information about services and their operations.

                    Columns depend on the API type:

                    * **REST**: service, version, method, path

                    * **GraphQL**: service, version, type, method

                    '
                  type: string
                  format: binary
                servicesWorkspaceId:
                  type: string
                  description: Id of the workspace in which the system will search for packages for the services specified in the CSV file.
                version:
                  description: Version name for publication in the dashboard.
                  type: string
                  example: '2022.3'
                previousVersion:
                  description: Name of the previous published version in the dashboard.
                  type: string
                  example: '2022.2'
                previousVersionPackageId:
                  description: packageId of the previous version. The parameter may be empty if the value is equal to the packageId.
                  type: string
                  example: NC.CloudBSS.CPQ.Q-TMF
                status:
                  $ref: '#/components/schemas/VersionStatusEnum'
                versionLabels:
                  description: List of version labels in dashboard version.
                  type: array
                  items:
                    type: string
                  example:
                  - part-of:CloudBSS-CPQBE
      responses:
        '202':
          description: Publish process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  publishId:
                    type: string
                    description: Publish process Id
                    format: uuid
                    example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
                PreviousVersionNotRelease:
                  $ref: '#/components/examples/PreviousVersionNotRelease'
                VersionReferencedAsPreviousByRelease:
                  $ref: '#/components/examples/VersionReferencedAsPreviousByRelease'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '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'
        '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}/copy:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    post:
      tags:
      - Publish
      summary: Copy package version to another package
      description: 'Publish package version in target package using sources of source package (server-side building only).\

        The final specifications will be stored using the POST /packages/{packageId}/publish/{publishId}/status. 202 response and the publish process Id will be returned in success.

        '
      operationId: getPackageIdVersionIdCopy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - targetPackageId
              - targetVersion
              - targetStatus
              properties:
                targetPackageId:
                  description: Target package unique identifier (full alias).
                  type: string
                  example: QS.CQSS.CPQ.TMF
                targetVersion:
                  description: Version name for publication in target package.
                  type: string
                  example: '2022.3'
                targetPreviousVersion:
                  description: Name of the previous published version in target package.
                  type: string
                  example: '2022.2'
                targetPreviousVersionPackageId:
                  description: Package id of the previous version. The parameter may be empty if the value is equal to the targetPackageId.
                  type: string
                  example: QS.CloudQSS.CPQ.Q-TMF
                targetStatus:
                  $ref: '#/components/schemas/VersionStatusEnum'
                targetVersionLabels:
                  description: List of version labels in target package.
                  type: array
                  items:
                    type: string
                  example:
                  - part-of:CloudQSS-CPQBE
      responses:
        '202':
          description: Publish process started
          content:
            application/json:
              schema:
                type: object
                title: serverBuild
                properties:
                  publishId:
                    type: string
                    description: Publish process Id
                    format: uuid
                    example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
        '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: {}
        '403':
          description: Forbidden. No permission to publish version in current status in target package.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '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}/groups/{groupName}/publish:
    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
        - graphql
        - asyncapi
    - name: groupName
      in: path
      required: true
      description: Name of the operation group
      schema:
        type: string
    post:
      tags:
      - Publish
      summary: Start operation group publication
      description: 'Start operation group publish process.\

        In this process all operations from operation group will be published to the selected package version.

        '
      operationId: postOperationGroupPublish
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - packageId
              - version
              - status
              properties:
                packageId:
                  description: Package unique identifier (full alias).
                  type: string
                  example: QS.CQSS.CPQ.TMF
                version:
                  description: Version name for publication in package.
                  type: string
                  example: '2022.3'
                previousVersion:
                  description: Name of the previous published version in package.
                  type: string
                  example: '2022.2'
                previousVersionPackageId:
                  description: Package id of the previous version. The parameter may be empty if the value is equal to the packageId.
                  type: string
                  example: QS.CloudQSS.CPQ.Q-TMF
                status:
                  $ref: '#/components/schemas/VersionStatusEnum'
                versionLabels:
                  description: List of version labels in package.
                  type: array
                  items:
                    type: string
                  example:
                  - part-of:CloudQSS-CPQBE
      responses:
        '202':
          description: Publish process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  publishId:
                    type: string
                    description: Publish process Id
                    format: uuid
                    example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
                PreviousVersionNotRelease:
                  $ref: '#/components/examples/PreviousVersionNotRelease'
                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'
        '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}/groups/{groupName}/publish/{publishId}/status:
    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
        - graphql
        - asyncapi
    - name: groupName
      in: path
      required: true
      description: Name of the operation group
      schema:
        type: string
    - name: publishId
      description: Publish Id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
      - Publish
      summary: Get operation group publication status
      description: 'Get operation group publish status.

        '
      operationId: getOperationGroupPublishStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Publish process status.
                    type: string
                    enum:
                    - running
                    - error
                    - complete
                    - none
                  message:
                    description: The message for **error** status.
                    type: string
        '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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/publish/availableStatuses:
    parameters:
    - $ref: '#/components/parameters/packageId'
    get:
      tags:
      - Publish
      summary: Get a list of available publish statuses for the package
      deprecated: true
      description: 'Get a list of available publish statuses for the package.

        List depends on the current user access rights.

        '
      operationId: getPackagesIdAvailableStatuses
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  statuses:
                    description: List of available statuses.
                    type: array
                    items:
                      $ref: '#/components/schemas/VersionStatusEnum'
        '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/users/{userId}/availablePackagePromoteStatuses:
    post:
      x-nc-api-audience: noBWC
      tags:
      - Publish
      summary: Get list of available package publish statuses for the user.
      description: 'By collection of packages, **get** the available statuses for publish into for the particular user.


        Statuses list depends on the current user access rights for the particular package.


        The response is a **mapped list** of statuses to the packageIds.

        '
      operationId: getUsersIdAvailablePackagePromoteStatuses
      parameters:
      - name: userId
        description: Unique user login (username) used to authenticate the user.
        in: path
        required: true
        schema:
          type: string
          example: user1221
      requestBody:
        description: Packages list to check.
        content:
          application/json:
            schema:
              type: object
              required:
              - packages
              properties:
                packages:
                  description: PackageIds list.
                  type: array
                  items:
                    type: string
                  example:
                  - QS.CloudQSS.CPQ.Q-TMF
                  - QS.CloudQSS.CPQ.QE-SRV
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List of packages and available statuses.
                additionalProperties:
                  type: array
                  description: Mapped list of statuses to the packageId.
                  items:
                    type: string
                    enum:
                    - draft
                    - release
                example:
                  QS.CloudQSS.CPQ.Q-TMF:
                  - draft
                  - release
                  QS.CloudQSS.CPQ.QE-SRV:
                  - draft
        '400':
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          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'
  /api/v2/packages/{packageId}/publish/statuses:
    get:
      tags:
      - Publish
      summary: Get builds statuses
      description: 'Get statuses for multiple publish operations.

        Note: In Service.go this endpoint is implemented as POST, but CSV specifies GET.

        '
      operationId: getPublishStatuses
      parameters:
      - $ref: '#/components/parameters/packageId'
      - name: publishIds
        in: query
        required: false
        description: List of publish IDs to get statuses for
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    publishId:
                      type: string
                    status:
                      type: string
                    message:
                      type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          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'
components:
  examples:
    Unauthorized:
      description: Unauthorized access
      value:
        status: 401
        code: APIHUB-4101
        message: Authentication required
    PackageNotFound:
      description: Package not found by ID. Response for the 404 error
      value:
        status: 404
        code: APIHUB-3020
        message: package with packageId = $packageId not found
    IncorrectInputParameters:
      description: Incorrect input parameters
      value:
        status: 400
        code: APIHUB-COMMON-4001
        message: Incorrect input parameters
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    VersionReferencedAsPreviousByRelease:
      description: Version cannot be changed to 'draft' because a released version uses it as its previous version
      value:
        status: 400
        code: '8600'
        message: 'Version 2024.1 for package QS.group.my-package cannot be changed to the ''draft'' status because it is the previous version of released versions: QS.group.other-package|2024.2@1'
        params:
          version: '2024.1'
          packageId: QS.group.my-package
          releaseVersions: QS.group.other-package|2024.2@1
    PreviousVersionNotRelease:
      description: A release version cannot reference a draft previous version
      value:
        status: 400
        code: '8600'
        message: Version 2024.2 for package QS.group.my-package cannot be published with the 'release' status because previous version 2024.1 for package QS.group.previous-package is in the 'draft' status. Change the previous version to 'release', or publish this version as a draft.
        params:
          version: '2024.2'
          packageId: QS.group.my-package
          previousVersion: '2024.1'
          previousVersionPackageId: QS.group.previous-package
  schemas:
    VersionStatusEnum:
      description: Package version status
      type: string
      enum:
      - draft
      - release
      - archived
    ApiType:
      title: apiType
      type: string
      enum:
      - rest
      - graphql
      - protobuf
      - asyncapi
    ErrorResponse:
      description: Standard error response returned for failed requests. Includes HTTP status, internal error code, human-readable message, optional message parameters, and optional debug details (non-production only).
      type: object
      properties:
        status:
          description: HTTP status code as an integer; expected to match the actual HTTP response status.
          type: number
        code:
          description: Internal string error code. Mandatory in response.
          type: string
        message:
          description: Human-readable error message describing what went wrong; intended for diagnostics and safe client display.
          type: string
        params:
          type: object
          description: Optional key/value parameters used to format or contextualize the error message (for example, identifiers or field names).
          example:
            id: 12345
            type: string
        debug:
          description: Optional debug details (for example, stack traces). Returned only in development/test environments when verbose logging is enabled; do not rely on this field in production because it may contain sensitive data.
          type: string
      required:
      - status
      - code
      - message
    BuildConfig:
      type: object
      description: 'Configuration of the source files.

        Content can not be empty, files or refs are **required**.

        '
      required:
      - version
      - status
      properties:
        version:
          description: Version name for publication.
          type: string
          example: '2022.3'
        previousVersion:
          description: 'Name of the previous published version.

            The mask <version>@<revision> is required for ''changelog'' buildType.

            '
          type: string
          example: '2022.2'
          default: ''
        previousVersionPackageId:
          description: 'Required in case of snapshot when publishing version should be compared to different package.

            Do not set anything if the package sould be compared to itself. Value equals to packageId is forbidden.

            '
          type: string
          example: QS.CloudOSS.PL.MC
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        validationRulesSeverity:
          type: object
          description: Configuration for validation rules severity levels
          readOnly: true
          properties:
            brokenRefs:
              type: string
              enum:
              - error
              - warning
              default: warning
              description: Severity level for broken references validation
        groupName:
          description: 'Operation group name. groupName is required if buildType = documentGroup.

            '
          type: string
          example: v1
        apiType:
          $ref: '#/components/schemas/ApiType'
        buildType:
          description: 'Type of the build process. Available options are:


            **build** - Standard build process to publish new version.

            Consist of contract and operations build and validation, calculation of the changelog, creation of the final version of the published contracts.


            **changelog** - Only the changelog calculation, no API contracts version will be created.

            The ```files``` and ```refs``` objects are not required in this case.


            **prefix-groups-changelog** - Changelog calculation for prefixed operation groups.


            **documentGroup** - Deprecated. Process to transform documents so that they will contain operations only from specific operations group.


            **exportGraphqlOperationsGroup** - Export GraphQL operations group.


            **exportAsyncapiOperationsGroup** - Export AsyncAPI operations group.

            '
          type: string
          enum:
          - build
          - changelog
          - prefix-groups-changelog
          - documentGroup
          - exportGraphqlOperationsGroup
          - exportAsyncapiOperationsGroup
          default: build
        metadata:
          description: Common publish metadata.
          type: object
          properties:
            commitId:
              description: Last Git commit ID of the version.
              type: string
              example: a5d45af7
            repositoryUrl:
              description: Url of the Git repository.
              type: string
              format: URI
              example: https://<git_group_link>/apihub-registry
            versionLabels:
              description: List of version labels. Label is a string.
              type: array
              items:
                type: string
              example:
              - part-of:CloudQSS-CPQBE
            cloudName:
              description: Name of the cloud for publication from Agent.
              type: string
              example: k8s-apps2
            cloudUrl:
              description: Full address of the cloud from Agent.
              type: string
              format: URI
              example: https://k8s-apps2.k8s.sdntest.qubership.org
            namespace:
              description: Namespace of Agent's publication.
              type: string
              example: cloudQSS-release2
        externalMetadata:
          description: External build metadata
          type: object
          properties:
            operations:
              type: array
              items:
                type: object
                properties:
                  apiType:
                    type: string
                    enum:
                    - rest
                  method:
                    type: string
                    description: HTTP method
                  path:
                    type: string
                    description: HTTP path
                  externalMetadata:
                    description: External operation metadata
                    type: object
        files:
          description: 'Detailed data about files in sources archive.

            Required if no Refs are provided.

            '
          type: array
          items:
            type: object
            required:
            - fileId
            properties:
              fileId:
                type: string
                description: File name.
                example: qitmf-v5.11.json
              publish:
                description: 'Flag, publish the source file or not.

                  Required for case with external refs when specification is separated into multiple files.

                  After dereference in scope of build process the source files(parts) are no longer required. So it''s possible to skip publish of such files.

                  '
                type: boolean
                default: true
              labels:
                description: List of file labels. Label is a string.
                type: array
                items:
                  type: string
                example:
                - TMF
              blobId:
                description: Git blob ID of the file.
                type: string
                example: a5d45af7
              xApiKind:
                description: Custom x-api-kind parameter for the file. Specify if this API is backward compatible.
                type: string
                example: no-BWC
              metadata:
                description: 'Open-ended file-level metadata.

                  For MCP discovery files, set `mcpEndpoint` to the MCP server URL; DDL files typically omit this object.

                  '
                type: object
                additionalProperties: true
                example:
                  mcpEndpoint: https://api.example.com/mcp
        refs:
          description: 'Detailed data about referenced versions for current package version.

            Required if no Files provided.

            '
          type: array
          items:
            type: object
            required:
            - refId
            - version
            - type
            properties:
              refId:
                description: Referenced package Id. I.e. link to another package.
                type: string
                example: QS.CloudQSS.CPQ.CORE
              version:
                description: Referenced package version. I.e. link to another package's version. The mask <version>@<revision> may be used to link with a specific revision. If the @revision is not provided, the latest version's revision will be used.
                type: string
                example: 2022.3@5
              parentRefId:
                description: Required to build reference(dependencies) graph. Allows to specify the parent node package id in the graph.
                type: string
                example: QS.CloudQSS.CPQ.CORE
              parentVersion:
                description: 'Required to build reference(dependencies) graph. Allows to specify the parent node version in the graph.

                  The mask <version>@<revision> may be used to link with a specific revision.

                  If the @revision is not provided, the latest version''s revision will be used.

                  '
                type: string
                example: 2022.2@4
              excluded:
                description: 'Required for conflict resolution case when different versions of the same package appear in the publication config.

                  All excluded refs will be ignored (but will still be visible for package version).

                  '
                type: boolean
  parameters:
    packageId:
      name: packageId
      in: path
      description: Package unique identifier (full alias)
      required: true
      schema:
        type: string
        example: QS.CloudQSS.CPQ.Q-TMF
    version:
      name: version
      in: path
      description: Package version
      required: true
      schema:
        type: string
        example: '2022.3'
  securitySchemes:
    BearerAuth:
      type: http
      description: 'Bearer token authentication (JWT). Default security scheme for API usage. Provide Authorization: Bearer <token>.'
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: apihub-access-token
      description: Authentication via the `apihub-access-token` cookie.
    api-key:
      type: apiKey
      description: API key authentication. Send the key in the api-key header.
      name: api-key
      in: header
    BasicAuth:
      type: http
      description: Login/password authentication.
      scheme: basic
    PersonalAccessToken:
      type: apiKey
      description: Personal access token authentication. Send the token in the X-Personal-Access-Token header; use for user-issued/script access.
      name: X-Personal-Access-Token
      in: header
    RefreshTokenAuth:
      type: apiKey
      in: cookie
      name: apihub-refresh-token
      description: Authentication via refresh token cookie
externalDocs:
  description: Find out more about this project and repository documentation
  url: https://github.com/Netcracker/qubership-apihub