Netcracker Publish API

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:
                  $re

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