Qubership APIHUB System Administrators API

openapi: 3.0.3
info:
  title: APIHUB system administrators API – External
  description: |
    External API contract for system administrators. This API covers technical administration operations such as package transitions, role management, administrator management, and selected operational actions. All endpoints require authenticated access and are intended for trusted administrative users.
  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
externalDocs:
  description: Find out more about this project and repository documentation
  url: https://github.com/Netcracker/qubership-apihub
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: Transition
    description: Operations to move packages
  - name: System
    description: System operations
  - name: Admin
    description: APIs for technical administration.
  - name: Roles
    description: APIs for role management.

paths:
  "/api/v2/admin/transition/move":
    post:
      tags:
        - Transition
      summary: Move package
      description: "Change a package ID (rename or move to another parent package). This is an asynchronous operation: the response returns an operation ID, and clients must query /api/v2/admin/transition/move/{id} to track status and completion."
      operationId: movePackage
      requestBody:
        description: Parameters of the source package ID and destination package ID used for the move operation.
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: Source package ID to move. The package must exist and be accessible to the caller.
                to:
                  type: string
                  description: Destination package ID after the move. The value must be unique and valid for package naming rules.
                overwriteHistory:
                  type: boolean
                  description: If true, force move even when the source package ID is already redirected to another package. The previous transition record is removed and that redirect is no longer available.
            examples: {}
        required: true

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                description: Move package response
                type: object
                properties:
                  id:
                    description: Move process id
                    type: string
        "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 or incorrect 'from' ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"

  /api/v2/admin/transition/move/{id}:
    get:
      tags:
        - Transition
      summary: Get move status
      description: |
        Retrieve the status of an asynchronous move operation by operation ID, including progress, timestamps, and resulting package identifiers.
      operationId: getMoveStatus
      parameters:
        - name: id
          description: ID of the move operation returned by the move request (string identifier).
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransitionStatus"
        "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 or incorrect ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"

  /api/v2/admin/transition/activity:
    get:
      tags:
        - Transition
      summary: List completed transition activities
      description: |
        List completed transition activities. Supports offset/limit pagination for recent completed operations.
      operationId: listActivities
      parameters:
        - name: offset
          in: query
          description: Transition activities offset
          schema:
            type: number
            default: 0
        - name: limit
          in: query
          description: Maximun items in response
          schema:
            type: number
            default: 100
            maximum: 100
            minimum: 1
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                description: Transition activities list
                type: object
                properties:
                  changes:
                    type: array
                    items:
                      $ref: "#/components/schemas/TransitionStatus"
        "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"
  /api/v2/admin/transition:
    get:
      tags:
        - Transition
      summary: List transitions
      description: |
        Retrieve the full mapping of historical package ID transitions (oldPackageId to newPackageId).
      operationId: listPackageTransitions
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                description: Transition activities list
                type: object
                properties:
                  changes:
                    type: array
                    items:
                      type: object
                      properties:
                        oldPackageId:
                          description: Package id that was before transition
                          type: string
                        newPackageId:
                          description: New package id after transition
                          type: string
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples: {}
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples: {}
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v2/roles":
    post:
      tags:
        - Roles
      summary: Create a new role
      description: |
        Create a new role with the set of available permissions for this role.

        The role may be assigned to the user for the specific package.

        The "read content of public packages" permissions is applied for all roles by default (except the private packages with default role = **none**).
      operationId: postRoles
      requestBody:
        description: Role creation parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleCreate"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Role"
                  - type: object
                    properties:
                      permissions:
                        type: array
                        description: List of permissions applicable to the role.
                        items:
                          $ref: "#/components/schemas/Permission"
                        example: ["read", "create_and_update_package", "delete_package"]
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/api/v2/roles/{roleId}":
    parameters:
      - name: roleId
        in: path
        required: true
        description: Unique role identifier (slug). Lowercase letters, digits, and hyphens are expected; value is immutable for an existing role.
        schema:
          type: string
          pattern: "^[a-z0-9-]"
          example: editor
    patch:
      tags:
        - Roles
      summary: Update role
      description: |
        Update role parameters.

        If a parameter is not provided in the request, its value remains unchanged.

        Read-only roles cannot be updated.
      operationId: patchRolesId
      requestBody:
        description: Role update payload. Omitted fields are left unchanged; provided permissions replace the current permission list.
        content:
          application/json:
            schema:
              type: object
              required:
                - permissions
              properties:
                permissions:
                  description: |
                    List of role permissions.
                    Current role permissions will be replaced by the transmitted list.
                  type: array
                  items:
                    $ref: "#/components/schemas/Permission"
                  example: ["read", "create_and_update_package", "delete_package"]
      responses:
        "204":
          description: No content
          content: {}
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
    delete:
      tags:
        - Roles
      summary: Delete role
      description: |
        Permanently delete a role and its permission assignment.

        When a role is deleted, users that had this role are removed from package membership lists where it was assigned.

        Roles with **readOnly:true** cannot be deleted.
      operationId: deleteRolesId
      responses:
        "204":
          description: No content
          content: {}
        "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"
  "/api/v2/roles/changeOrder":
    post:
      tags:
        - Roles
      summary: Update the roles order
      description: |
        Replace the global role display/order configuration with the submitted ordered list.

        The request must contain each existing role exactly once; missing or duplicate role IDs cause a 400 error. The change is applied atomically.
      operationId: postRolesChangeOrder
      requestBody:
        description: Ordered list of role IDs representing the complete desired role order.
        content:
          application/json:
            schema:
              type: object
              description: Payload containing the complete ordered role list. Order is significant and all existing roles must be present exactly once.
              required:
                - roles
              properties:
                roles:
                  type: array
                  items:
                    type: string
                  example: [admin, owner, editor, viewer, none]
      responses:
        "204":
          description: No content
          content: {}
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/api/v2/admins":
    get:
      x-nc-api-audience: noBWC
      tags:
        - Roles
      summary: Get list of system administrators
      description: Retrieve all users currently configured as system administrators.
      operationId: getAdmins
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  admins:
                    description: List of system administrators.
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          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"
    post:
      x-nc-api-audience: noBWC
      tags:
        - Roles
      summary: Add a system administrator
      description: |
        Add an existing user as a system administrator.
      operationId: postAdmins
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
              properties:
                userId:
                  description: User login (username), for example user1221.
                  type: string
                  example: user1221
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  admins:
                    description: List of system administrators.
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
        "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"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v2/admins/{userId}":
    delete:
      x-nc-api-audience: noBWC
      tags:
        - Roles
      summary: Delete system administrator
      description: Delete a user from the system administrators group.
      operationId: deleteAdminsId
      parameters:
        - name: userId
          description: User login (username), for example user1221.
          in: path
          required: true
          schema:
            type: string
            example: user1221
      responses:
        "204":
          description: No content
          content: {}
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v1/builds":
    get:
      tags:
        - Admin
      summary: List builds
      description: |
        Return a page of builds with persisted build configuration. If no filter is provided, the latest builds are returned first.
      operationId: listBuilds
      parameters:
        - name: packageId
          in: query
          required: false
          description: Filter builds by package ID.
          schema:
            type: string
        - name: version
          in: query
          required: false
          description: Filter builds by package version.
          schema:
            type: string
        - name: buildIds
          in: query
          required: false
          description: Comma-separated list of build IDs. When combined with other filters, all filters are applied.
          schema:
            type: string
        - name: offset
          in: query
          required: false
          description: Number of items to skip.
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of items to return.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 100
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtendedBuilds"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v1/builds/{buildId}":
    get:
      tags:
        - Admin
      summary: Get build
      description: |
        Return build data and persisted build configuration by build ID.
      operationId: getBuild
      parameters:
        - name: buildId
          in: path
          required: true
          description: Build identifier string returned by build operations.
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtendedBuild"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Build 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"
  "/api/v2/admin/builds/{buildId}/result":
    get:
      tags:
        - Admin
      summary: Get build result archive
      description: |
        Download the build result archive for a completed build. The response body is a binary stream (application/octet-stream) containing build artifacts.
      operationId: getBuildResult
      parameters:
        - name: buildId
          in: path
          required: true
          description: Build identifier string returned by build operations (internal build ID).
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Build result 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"
  "/api/v2/admin/builds/{buildId}/sources":
    get:
      tags:
        - Admin
      summary: Get build sources archive
      description: |
        Download build sources archive by build ID. The archive includes an apihub_build_config.json file with the build configuration.
      operationId: getBuildSources
      parameters:
        - name: buildId
          in: path
          required: true
          description: Build identifier string returned by build operations (internal build ID).
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Build sources 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"
  "/api/internal/migrate/operations":
    post:
      tags:
        - Admin
      summary: Start operations migration
      description: |
        Start an asynchronous operations migration job. Use the returned migration ID to check status, reports, and diagnostics endpoints.
      operationId: startOpsMigration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                packageIds:
                  type: array
                  items:
                    type: string
                  description: Optional list of package IDs to migrate. If omitted, migration scope is determined by server-side defaults.
                versions:
                  type: array
                  items:
                    type: string
                  description: Optional list of versions to migrate (for example, 1.0.0 or 1.0.0@2). If omitted, all eligible versions are processed.
                rebuildChangelogOnly:
                  type: boolean
                  description: If true, only changelog data is rebuilt; no full operations migration is performed.
                  default: false
                skipValidation:
                  type: boolean
                  description: If true, pre-migration validation checks are skipped. Use with caution because invalid data may propagate to reports.
                  default: false
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Migration ID
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflict - migration already running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/internal/migrate/operations/{migrationId}":
    get:
      tags:
        - Admin
      summary: Get migration status
      description: |
        Retrieve migration status and report data for a migration job identified by migrationId.
      operationId: getMigrationReport
      parameters:
        - name: migrationId
          in: path
          required: true
          description: Migration job identifier returned by the start migration operation.
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: Migration report
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          d

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