openapi: 3.2.0
info:
  title: APIHUB Registry – External Export 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: Export
  description: Export API documentation.
paths:
  /api/v1/export:
    post:
      tags:
      - Export
      summary: Async export of version, document or operations group
      description: 'Start export of package version, one document or operations group. Use ```GET /api/v1/export/{exportId}/status``` to get status of export and exported file itself.\

        Export of document is currently available for documents with type openapi-3-1, openapi-3-0, or openapi-2-0 and is intended to retrieve content with some transformations. For other document types, use GET /api/v2/packages/{packageId}/versions/{version}/files/{slug} to obtain the original document content.\

        Export of operations group is currently available for groups with apiType = REST, GraphQL or AsyncAPI.

        '
      operationId: postExport
      requestBody:
        description: "Defines an entity that shall be exported and export settings.\\\nThe following entities can be exported:\n  - **version** - export of all documents from the version.\n  - **OpnAPI document** - export of one specific document with type openapi-3-1, openapi-3-0, or openapi-2-0.\n  - **REST operations group** - export of operations group. Only operations group with apiType = REST can be exported.\n  - **GraphQL operations group** - export of operations group. Only operations group with apiType = GraphQL can be exported.\n  - **AsyncAPI operations group** - export of operations group. Only operations group with apiType = AsyncAPI can be exported.\n"
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/ExportVersion'
              - $ref: '#/components/schemas/ExportRestDocument'
              - $ref: '#/components/schemas/ExportRestOperationsGroup'
              - $ref: '#/components/schemas/ExportGraphqlOperationsGroup'
              - $ref: '#/components/schemas/ExportAsyncapiOperationsGroup'
              discriminator:
                propertyName: exportedEntity
      responses:
        '202':
          description: Export process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  exportId:
                    type: string
                    description: Export 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'
        '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'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/export/{exportId}/status:
    parameters:
    - name: exportId
      description: Export process id.
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
      - Export
      summary: Get status of async export
      description: 'Get status of async export operation (POST /api/v1/export). If file for export is ready, then it will be returned. The resulting file is stored temporarily; once deleted, it needs to be re-calculated.

        '
      operationId: getExportIdStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: 'Export process status.\

                      "none" status means - not started.

                      '
                    type: string
                    enum:
                    - running
                    - error
                    - none
                  message:
                    description: The message for **error** status.
                    type: string
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: 'File to download.

                  '
          headers:
            Content-Disposition:
              schema:
                type: string
                description: "File name for exported entity.\n  - if version was exported: <packageId>_<version>.<extension>\n  - if document was exported: <packageId>_<version>_<file name>.<extension>\n  - if operations group was exported: <packageId>_<version>_<group name>.<extension>\n"
                example: attachment; filename="PCKG1.zip"
        '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:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '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}/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:
      - Export
      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/v3/packages/{packageId}/versions/{version}/{apiType}/export/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
    get:
      deprecated: true
      x-deprecation-reason: POST /api/v1/export shall be used instead of the current operation.
      tags:
      - Export
      summary: Export operations group as OpenAPI documents
      description: 'Export all operations from an operations group (with apiType = REST API) as OpenAPI specification(s).

        '
      operationId: getPackagesIdVersionsIdExportGroupNameV3
      parameters:
      - name: format
        in: query
        required: true
        description: 'Format of the exported file.\

          If buidType = reducedSourceSpecifications, then format can be yaml, json or html.\

          If buidType = mergedspecification, then format can be yaml or json; html is not supported for this buildType.

          '
        schema:
          type: string
          enum:
          - yaml
          - json
          - html
          default: json
      responses:
        '200':
          description: Success
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: ZIP file to download. ZIP will be returned if buildType = reducedSourceSpecifications
            application/json:
              schema:
                type: string
                format: binary
                description: JSON file to download. JSON will be returned if buidType = mergedspecification and format = json
            application/yaml:
              schema:
                type: string
                format: binary
                description: YAML file to download. YAML will be returned if buidType = mergedspecification and format = yaml
          headers:
            Content-Disposition:
              schema:
                type: string
                description: File name
                example: attachment; filename="<groupName>_<package.id>_<version>.zip"
        '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: {}
        '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}/files/{slug}/doc:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/slug'
    get:
      deprecated: true
      x-deprecation-reason: POST /api/v1/export shall be used instead of the current operation.
      tags:
      - Export
      summary: Export offline API documentation by selected file
      description: 'Export of offline API documentation by selected file as a zip archive.

        Type of the documentation file is provided as input parameters:

        - interactive - html document

        - raw - yaml/json document.

        '
      operationId: getPackagesIdVersionsIdFilesSlugDoc
      parameters:
      - name: docType
        in: query
        description: Type of the exported documentation.
        required: false
        schema:
          type: string
          enum:
          - interactive
          - raw
          default: interactive
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Documentation ZIP file (if docType = interactive) or yaml/json (if docType = raw) to download
        '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'
                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}/sourceData:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    get:
      tags:
      - Export
      summary: Export sources of package version with build config
      description: 'Export sources of package version as a zip archive and build configuration that was used for this version.

        '
      operationId: getPackageVersionSourcesWithBuildConfig
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: Build configuration and ZIP file with package version sources to download
                properties:
                  sources:
                    type: string
                    description: ZIP file with package version sources to download
                  config:
                    $ref: '#/components/schemas/BuildConfig'
        '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
          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}/doc:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    get:
      deprecated: true
      x-deprecation-reason: POST /api/v1/export shall be used instead of the current operation.
      tags:
      - Export
      summary: Export offline API documentation by selected versions
      description: 'Export of offline API documentation by selected version (all files) as a zip archive.

        Type of the documentation file is provided as input parameters:

        * interactive - html document.

        '
      operationId: getPackagesIdVersionsIdDoc
      parameters:
      - name: docType
        in: query
        description: Type of the exported documentation.
        required: false
        schema:
          type: string
          enum:
          - interactive
          default: interactive
      responses:
        '200':
          description: Success
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: Documentation ZIP file to download
        '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'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/versions/{version}/ddl/export/entities:
    get:
      tags:
      - Export
      summary: Export DDL entities to xlsx file
      description: Export DDL contract entities of a package version. Only `table` entities are supported now.
      operationId: getPackageVersionDdlEntitiesExport
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - name: refPackageId
        description: Filter by package id of ref package, shall be used in case of dashboard.
        in: query
        schema:
          type: string
      - name: textFilter
        in: query
        description: Filter by DDL entity name (case-insensitive substring match).
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/xlsx:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="DDLEntities_package.id_version.xlsx"
        '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: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/versions/{version}/ddl/export/changes:
    get:
      tags:
      - Export
      summary: Export DDL changes to xlsx file
      description: Export DDL contract changes between two compared package versions. Only `table` entities are supported now.
      operationId: getPackageVersionDdlChangesExport
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/severity'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      - name: refPackageId
        description: Filter by package id of ref package and previous ref package.
        in: query
        schema:
          type: string
      - name: textFilter
        in: query
        description: Filter by DDL entity name (case-insensitive substring match).
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/xlsx:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="DDLChanges_package.id_version.xlsx"
        '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'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/versions/{version}/mcp/export/{entity}:
    get:
      tags:
      - Export
      summary: Export MCP contract entities to xlsx file
      description: Export MCP discovery contract entities of a package version.
      operationId: getPackageVersionMcpEntitiesExport
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/mcpEntity'
      - name: refPackageId
        description: Filter by package id of ref package, shall be used in case of dashboard.
        in: query
        schema:
          type: string
      - name: textFilter
        in: query
        description: Filter by MCP entity title and description (case-insensitive substring match).
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/xlsx:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="MCPEntities_package.id_version.xlsx"
        '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: {}
        '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}/export/shareability-report:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    get:
      tags:
      - Export
      summary: Generate shareability report
      description: 'Generate a shareability status xlsx report for all documents in a group, including all sub-groups and packages.

        Rows are sorted by package name, document name, slug. Requires read permission on the group.

        '
      operationId: generateShareabilityReport
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="shareability_report_group.id_2024.1_20240101120000.xlsx"
        '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'
        '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:
  parameters:
    slug:
      name: slug
      in: path
      description: File unique string identifier
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9-]
        example: qitmf-v5-11-json
    packageId:
      name: packageId
      in: path
      description: Package unique identifier (full alias)
      required: true
      schema:
        type: string
        example: QS.CloudQSS.CPQ.Q-TMF
    mcpEntity:
      name: entity
      in: path
      required: true
      description: MCP entity collection type.
      schema:
        type: string
        enum:
        - inits
        - tools
        - prompts
        - resources
    severity:
      name: severity
      in: query
      description: Filter API changes by severity.
      schema:
        type: array
        items:
          type: string
          enum:
          - breaking
          - non-breaking
          - deprecated
          - semi-breaking
          - annotation
          - unclassified
    previousVersion:
      name: previousVersion
      in: query
      description: 'Package previous version.

        If both previousVersion and previousVersionPackageId are not specified, then the previous **release** version will be used.

        '
      schema:
        type: string
        example: '2022.3'
    version:
      name: version
      in: path
      description: Package version
      required: true
      schema:
        type: string
        example: '2022.3'
    previousVersionPackageId:
      name: previousVersionPackageId
      in: query
      description: 'Package unique identifier for previous version.

        If both previousVersion and previousVersionPackageId are not specified, then the previous **release** version will be used.

        '
      schema:
        type: string
        example: QS.RUNENV.K8S-SERVER.CJM-QSS-DEV-2.Q-TMF
  schemas:
    ExportAsyncapiOperationsGroup:
      type: object
      title: Export AsyncAPI operations group
      description: 'Export settings for exporting the operations group. The option is applicable only for groups with apiType = AsyncAPI.

        The export result is a ZIP file containing AsyncAPI specifications for all operations from the group.

        '
      required:
      - exportedEntity
      - packageId
      - version
      - groupName
      - format
      properties:
        exportedEntity:
          description: The entity to be exported.
          type: string
          enum:
          - asyncapiOperationsGroup
        packageId:
          description: Package unique string identifier (full alias).
          type: string
          example: WS.GRP.PCKG
        version:
          description: Package version.
          type: string
          example: '2024.2'
        groupName:
          description: Name of the operations group to export. Group must have apiType = AsyncAPI
          type: string
        format:
          description: Format of the exported file.
          type: string
          enum:
          - yaml
          - json
    VersionStatusEnum:
      description: Package version status
      type: string
      enum:
      - draft
      - release
      - archived
    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
    ExportGraphqlOperationsGroup:
      type: object
      title: Export GraphQL operations group
      description: 'Export settings for exporting the operations group. The option is applicable only for groups with apiType = GraphQL.

        The export result is a ZIP file containing GraphQL schema files for all operations from the group.

        '
      required:
      - exportedEntity
      - packageId
      - version
      - groupName
      properties:
        exportedEntity:
          description: The entity to be exported.
          type: string
          enum:
          - graphqlOperationsGroup
        packageId:
          description: Package unique string identifier (full alias).
          type: string
          example: WS.GRP.PCKG
        version:
          description: Package version.
          type: string
          example: '2024.2'
        groupName:
          description: Name of the operations group to export. Group must have apiType = GraphQL
          type: string
    ExportRestDocument:
      type: object
      title: Export one OpenAPI document
      description: 'Export settings for exporting one document. The option is applicable only for document types - openapi-3-1 / openapi-3-0 / openapi-2-0.

        The export result is determined by the "format" parameter.

        '
      required:
      - exportedEntity
      - packageId
      - version
      - documentId
      - format
      properties:
        exportedEntity:
          description: The entity to be exported.
          type: string
          enum:
          - restDocument
        packageId:
          description: Package unique string identifier (full alias).
          type: string
          example: WS.GRP.PCKG
        version:
          description: Package version
          type: string
          example: '2024.2'
        documentId:
          description: Unique string identifier of document to export. Type of this document must be openapi-3-1 / openapi-3-0 / openapi-2-0.
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
        format:
          description: 'File format for export.

            '
          type: string
          enum:
          - yaml
          - json
          - html
        removeOasExtensions:
          description: 'Flag defines whether OAS extensions shall be removed (taking into account allowed list of OAS extensions defined on package) from exported specification or not.

            '
          type: boolean
          default: false
    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
    ExportVersion:
      type: object
      title: Export entire version
      description: "Export settings for exporting a version (i.e., all documents from the version). Only version of package with kind = package can be exported.\\\n  * format = html: the export result includes a ZIP file containing interactive HTML for OpenAPI documents (i.e., those with types openapi-3-1, openapi-3-0, or openapi-2-0) and raw files for all other document types.\n  * format = yaml/json: the export result includes a ZIP file containing OpenAPI documents in yaml/json format accordingly, and raw files for all other document types.\n"
      required:
      - exportedEntity
      - packageId
      - version
      - format
      properties:
        exportedEntity:
          description: The entity to be exported.
          type: string
          enum:
          - version
        packageId:
          description: Package unique string identifier (full alias) of package with kind = package.
          type: string
          example: WS.GRP.PCKG
        version:
          description: Package version
          type: string
          example: '2024.2'
        removeOasExtensions:
          description: 'Flag defines whether OAS extensions shall be removed (taking into

            account allowed list of OAS extensions defined on package) from

            exported OpenAPI specifications or not.

            '
          type: boolean
          default: false
        format:
          description: 'File format for export.

            '
          type: string
          enum:
          - yaml
          - json
          - html
        allowedShareabilityStatuses:
          description: 'Array of shareability statuses to filter documents during the export.

            '
          type: array
          items:
            type: string
            enum:
            - shareable
            - non-shareable
            - unknown
          default:
          - shareable
          - non-shareable
          - unknown
          example:
          - shareable
    ExportRestOperationsGroup:
      type: object
      title: Export REST operations group
      description: 'Export settings for exporting the operations group. The option is applicable only for groups with apiType = REST.

        The export result is determined by the "format" and "buildType" parameters.

        '
      required:
      - exportedEntity
      - packageId
      - version
      - groupName
      - operationsSpecTransformation
      - format
      properties:
        exportedEntity:
          description: The entity to be exported.
          type: string
          enum:
          - restOperationsGroup
        packageId:
          description: Package unique string identifier (full alias).
          type: string
          example: WS.GRP.PCKG
        version:
          description: Package version.
          type: string
          example: '2024.2'
        groupName:
          description: Name of the operations group to export. Group must have apiType = REST
          type: string
        operationsSpecTransformation:
          description: 'Type of 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.

            '
          type: string
          enum:
          - reducedSourceSpecifications
          - mergedSpecification
        format:
          description: "Format of the exported file.\\\nIf operationsSpecTransformation = reducedSourceSpecifications, then export result is a ZIP file containing files in selected format.\\\nIf operationsSpecTransformation = mergedSpecification:\n  * if format = html, then export result is a ZIP file containing interactive HTML for OpenAPI document.\n  * if format = yaml/json, then export result is one OpenAPI file in the appropriate format.\n"
          type: string
          enum:
          - yaml
          - json
          - html
        removeOasExtensions:
          description: 'Flag defines whether OAS extensions shall be removed (taking into

            account allowed list of OAS extensions defined on package) from

            exported specification or not.

            '
          type: boolean
          default: false
  examples:
    Unauthorized:
      description: Unauthorized access
      value:
        status: 401
        code: APIHUB-4101
        message: Authentication required
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    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
    VersionNotFound:
      description: Version not found by number. Response for the 404 error
      value:
        status: 404
        code: APIHUB-3050
        message: Published version $version not found
    IncorrectInputParameters:
      description: Incorrect input parameters
      value:
        status: 400
        code: APIHUB-COMMON-4001
        message: Incorrect input parameters
    FileNotFound:
      description: File not found by slug. Response for the 404 error
      value:
        status: 404
        code: APIHUB-3043
        message: File for path $fileId not found
  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