openapi: 3.2.0
info:
  title: APIHUB system administrators API – External Transition API
  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
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
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'
components:
  examples:
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    IncorrectInputParameters:
      description: Incorrect input parameters
      value:
        status: 400
        code: APIHUB-COMMON-4001
        message: Incorrect input parameters
  schemas:
    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
    TransitionStatus:
      type: object
      properties:
        id:
          type: string
          description: ID of the move operation returned by the move request (string identifier).
        trType:
          type: string
          description: Transition type
        fromId:
          type: string
          description: Source package ID before transition.
        toId:
          type: string
          description: Destination package ID after transition.
        status:
          type: string
          description: 'Current operation status (for example: pending, running, completed, failed).'
        startedBy:
          type: string
          description: User who started the operation
        startedAt:
          type: string
          description: Timestamp when the operation started (ISO 8601, UTC).
        finishedAt:
          type: string
          description: Timestamp when the operation finished (ISO 8601, UTC).
        progressPercent:
          type: integer
          format: int32
          description: Percentage complete (0-100, inclusive).
        affectedObjects:
          type: integer
          format: int32
          description: Number of affected rows in the database.
        completedSerialNumber:
          type: integer
          format: int32
          description: Serial number of the completed transition record (internal monotonic identifier).
  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
    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