Netcracker Packages API

openapi: 3.2.0
info:
  title: APIHUB Registry – External Packages 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: Packages
  description: APIs for the package management.
paths:
  /api/v4/activity:
    get:
      tags:
      - Packages
      summary: Get activity history
      description: 'Get activity history. Return the last N events in descending date order.

        '
      operationId: getActivityV4
      parameters:
      - name: onlyFavorite
        description: '* If true, then only events from packages that are favorites for the current user shall be returned (including all child groups/packages/dashboards for favorite groups/workspaces)

          * If false, events for all packages shall be returned.

          '
        in: query
        schema:
          type: boolean
          default: false
      - name: onlyShared
        in: query
        description: filter only shared packages
        schema:
          type: boolean
          default: false
      - name: kind
        in: query
        description: 'Filter by package kind.

          The list of values is acceptable. In this case, the following pattern will be used: ```?kind=group,package,dashboard```.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - workspace
            - group
            - package
            - dashboard
          example:
          - group
          - package
          - dashboard
      - name: types
        description: 'Filter for events by group types:

          * package_members - grant_role, update_role, delete_role.

          * package_security - generate_api_key, revoke_api_key.

          * new_version - publish_new_version.

          * package_version - patch_version_meta, delete_version, publish_new_revision, delete_revision.

          * package_management - create_package, delete_package, patch_package_meta.

          * operations_group - create_manual_group, delete_manual_group, update_operations_group_parameters

          '
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - package_members
            - package_security
            - new_version
            - package_version
            - package_management
            - operations_group
      - name: textFilter
        in: query
        description: Filter by userName/packageName
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      required:
                      - date
                      - principal
                      - packageId
                      - packageName
                      - kind
                      - params
                      properties:
                        date:
                          description: Date when event was generated
                          type: string
                          format: date-time
                        principal:
                          $ref: '#/components/schemas/ActivityHistoryPrincipal'
                        packageId:
                          description: Package unique string identifier (full alias)
                          type: string
                        packageName:
                          description: Package name
                          type: string
                        kind:
                          description: Package kind
                          type: string
                          enum:
                          - workspace
                          - group
                          - package
                          - dashboard
                        eventType:
                          description: Activity event type
                          type: string
                          enum:
                          - generate_api_key
                          - revoke_api_key
                          - create_package
                          - delete_package
                          - grant_role
                          - delete_role
                          - update_role
                          - publish_new_version
                          - delete_version
                          - delete_revision
                          - publish_new_revision
                          - patch_version_meta
                          - patch_package_meta
                          - create_manual_group
                          - delete_manual_group
                          - update_operations_group_parameters
                          - update_document_shareability
                        params:
                          type: object
                          description: Events specific params
                          oneOf:
                          - type: object
                            title: ParamsForGrantAndDeleteRole
                            description: params for grant_role and delete_role events
                            required:
                            - memberId
                            - memberName
                            - roles
                            properties:
                              memberId:
                                description: Login of the member
                                type: string
                                example: user1221
                              memberName:
                                description: User which was added/deleted to/from package with some role(s)
                                type: string
                                example: John Doe
                              roles:
                                type: array
                                items:
                                  $ref: '#/components/schemas/Role'
                          - type: object
                            title: ParamsForUpdateRole
                            description: params for update_role event
                            required:
                            - memberId
                            - memberName
                            properties:
                              memberId:
                                description: Login of the member
                                type: string
                                example: user1221
                              memberName:
                                description: User which was added/deleted to/from package with some role(s)
                                type: string
                                example: John Doe
                          - type: object
                            title: ParamsForPublishAndDeleteVersion
                            description: params for publish_new_version and delete_version events
                            required:
                            - version
                            - status
                            properties:
                              version:
                                description: Package version name.
                                type: string
                                example: '22.3'
                              status:
                                $ref: '#/components/schemas/VersionStatusEnum'
                          - type: object
                            title: ParamsForPublishNewRevision
                            description: params for publish_new_revision event
                            required:
                            - version
                            - revision
                            - status
                            properties:
                              version:
                                description: Package version name.
                                type: string
                                example: '22.3'
                              revision:
                                description: Number of the revision.
                                type: integer
                                format: int32
                                example: 3
                              status:
                                $ref: '#/components/schemas/VersionStatusEnum'
                          - type: object
                            title: ParamsForUpdateVersionMeta
                            description: params for patch_version_meta event
                            required:
                            - version
                            - versionMeta
                            properties:
                              version:
                                description: Package version name.
                                type: string
                                example: '22.3'
                              versionMeta:
                                description: List of parameters that was updated in version
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - status
                                  - label
                          - type: object
                            title: ParamsForPatchPackageMeta
                            description: params for patch_package_meta event
                            required:
                            - packageMeta
                            properties:
                              packageMeta:
                                description: List of parameters that was updated in package
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - name
                                  - description
                                  - serviceName
                                  - defaultRole
                          - type: object
                            title: ParamsForPostDeleteManualGroups
                            description: 'params for the following events:

                              * create_manual_group

                              * deleted_manual_group

                              '
                            required:
                            - version
                            - groupName
                            - apiType
                            properties:
                              version:
                                description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                type: string
                                example: 22.3@2
                              notLatestRevision:
                                type: boolean
                                default: false
                                description: If parameter is not returned, then it is latest revision.
                              groupName:
                                description: Manual group name
                                type: string
                              apiType:
                                type: string
                                enum:
                                - rest
                                - graphql
                                - protobuf
                                - asyncapi
                          - type: object
                            title: ParamsForPatchOperationsGroup
                            description: 'params for the update_operations_group_parameters event

                              '
                            required:
                            - version
                            - groupName
                            - groupsParams
                            - isPrefixGroup
                            - apiType
                            properties:
                              version:
                                description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                type: string
                                example: 22.3@2
                              apiType:
                                type: string
                                enum:
                                - rest
                                - graphql
                                - asyncapi
                              notLatestRevision:
                                description: If parameter is not returned, then it is latest revision.
                                type: boolean
                                default: false
                              groupName:
                                description: Manual group name
                                type: string
                              groupsParams:
                                description: List of parameters that was updated in group
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - name
                                  - description
                                  - template
                                  - operations
                              isPrefixGroup:
                                type: boolean
                                description: true - if the group created automatically via restGroupingPrefix.
                          - type: object
                            title: ParamsForDeleteRevision
                            description: 'params for delete_revision event

                              '
                            required:
                            - version
                            - status
                            properties:
                              version:
                                description: Package version name with revision. The <version>@<revision> format is used.
                                type: string
                                example: 4@2
                              status:
                                $ref: '#/components/schemas/VersionStatusEnum'
                          - type: object
                            title: ParamsForUpdateDocumentShareability
                            description: params for update_document_shareability event
                            required:
                            - version
                            - documentDisplayName
                            - shareabilityStatus
                            properties:
                              version:
                                description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                type: string
                                example: 22.3@2
                              notLatestRevision:
                                type: boolean
                                default: false
                                description: If parameter is not returned, then it is latest revision.
                              documentDisplayName:
                                description: Title + version of the document whose shareability was updated
                                type: string
                                example: API Specification 1.0.0
                              shareabilityStatus:
                                description: New shareability status
                                type: string
                                enum:
                                - shareable
                                - non-shareable
                                - unknown
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages:
    post:
      tags:
      - Packages
      summary: Create a new package
      description: Create a new package in APIHUB registry.
      operationId: postPackages
      requestBody:
        description: Package for creation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageCreate'
            examples: {}
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Package'
                - type: object
                  properties:
                    parents:
                      description: List of all parent packages
                      type: array
                      items:
                        $ref: '#/components/schemas/PackageList'
              examples: {}
        '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: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    get:
      tags:
      - Packages
      summary: Get packages list
      description: Retrieve the packages list.
      operationId: getPackages
      parameters:
      - name: parentId
        in: query
        description: Filter by the parent package Id.
        schema:
          type: string
          example: QS.CQSS.CPQ
      - name: kind
        in: query
        description: 'Filter the packages by kind.


          The list of values is acceptable. In this case, the following pattern will be used: ```?kind=group,package,dashboard```.


          If not transmitted, the default value will be used.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - workspace
            - group
            - package
            - dashboard
          default:
          - workspace
          example:
          - group
          - package
          - dashboard
      - name: showAllDescendants
        in: query
        description: 'Show all the descendants to the parent workspace or group.


          * If ```true```, return the list of all child groups/packages/dashboards to the parentId (take into account all other filter parameters).

          * If the parentId is not transmitted???

          * If the parent is transmitted, but kind not - and parentId = package???

          '
        schema:
          type: boolean
          default: false
      - name: textFilter
        in: query
        description: filter by name/alias/label.
        schema:
          type: string
      - name: onlyFavorite
        in: query
        description: filter only favorite packages
        schema:
          type: boolean
          default: false
      - name: onlyShared
        in: query
        description: filter only shared packages
        schema:
          type: boolean
          default: false
      - name: lastReleaseVersionDetails
        in: query
        description: 'Show/hide the detailed info about the last release version and it''s changes, comparing with the previous one.

          '
        schema:
          type: boolean
          default: false
      - name: serviceName
        description: Service name that package belongs to. Should be equal to service deployment name in kubernetes.
        in: query
        schema:
          type: string
          example: quote-tmf-service
      - $ref: '#/components/parameters/showParents'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: Whole packages list with paging.
                type: object
                properties:
                  packages:
                    type: array
                    title: Detailed package
                    items:
                      required:
                      - packageId
                      - alias
                      - name
                      allOf:
                      - $ref: '#/components/schemas/Package'
                      - type: object
                        properties:
                          parents:
                            description: List of all parent packages
                            type: array
                            items:
                              $ref: '#/components/schemas/PackageList'
                          lastReleaseVersionDetails:
                            type: object
                            description: 'Details about the last release version and it''s changes with previous version.

                              * Returns only if the lastReleaseVersionDetails:true and the lastReleaseVersion is explicitly filled in on a package.

                              * Otherwise - will be omitted in the answer.

                              '
                            properties:
                              version:
                                description: 'Last release version specified on the package.The <version>@<revision> mask is used to return the revision number.

                                  '
                                type: string
                                example: 2022.4@2
                              notLatestRevision:
                                type: boolean
                                default: false
                              summary:
                                $ref: '#/components/schemas/ChangeSummary'
              examples: {}
        '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: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    get:
      tags:
      - Packages
      summary: Get package by Id
      description: Common information about the selected package without files and references.
      operationId: getPackagesId
      parameters:
      - $ref: '#/components/parameters/showParents'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Package'
                - type: object
                  properties:
                    parents:
                      description: List of all parent packages
                      type: array
                      items:
                        allOf:
                        - $ref: '#/components/schemas/PackageList'
                        - type: object
                          properties:
                            hasReadPermission:
                              type: boolean
                              description: true - if current user has read permission fot this package
                    defaultReleaseVersion:
                      description: 'Default release version for the package.

                        Only `release` version may be placed as default. Return the error otherwise.

                        The <version>@<revision> mask is used to return the revision number.

                        '
                      type: string
                      example: 2023.1@5
                    defaultVersion:
                      description: 'Default release version for the package.

                        It is calculable by the algorithm:

                        * If defaultReleaseVersion is filled in on the package explicitly, return it.

                        * If not - return the last published version (by name) with "release" status.

                        * If there were no published release versions, return the last published "draft" version (by date).

                        * Otherwise - return "".

                        The <version>@<revision> mask is used to return the revision number.

                        '
                      type: string
                      example: 2023.1@5
              examples:
                Package:
                  $ref: '#/components/examples/Package'
        '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:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    patch:
      tags:
      - Packages
      summary: Change the package's parameters
      description: 'Change the package''s parameters.

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

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

        '
      operationId: patchPackagesId
      requestBody:
        description: Package update parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageUpdate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Package'
                - type: object
                  properties:
                    parents:
                      description: List of all parent packages
                      type: array
                      items:
                        $ref: '#/components/schemas/PackageList'
                    defaultReleaseVersion:
                      description: 'Default release version for the package.

                        Only `release` version may be placed as default. Return the error otherwise.

                        '
                      type: string
                      example: '2023.1'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      tags:
      - Packages
      summary: Delete package
      description: Delete the package and all included published versions.
      operationId: deletePackagesId
      responses:
        '204':
          description: No content
          content: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
          

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