DealHub Version Management API

openapi: 3.2.0
info:
  title: Version Management API
  description: 'This API provides a comprehensive set of services for managing versions and the associated product catalog within the DealHub CPQ system. It allows for system-to-system integration to get, create, duplicate, activate, and manage the content of versions.


    Several operations, such as duplicating, activating, and uploading a product catalog, are asynchronous. These endpoints return a `request_id` for tracking.


    All requests require a secret Bearer Token in the `Authorization` header, which is generated by a CPQ administrator.'
  version: 1.0.0
servers:
- url: https://api.dealhub.io
  description: The base URL for your DealHub instance.
  variables:
    your-dealhub-instance:
      default: app
      description: Your specific DealHub instance name (e.g., 'app', 'service-eu1').
security:
- bearerAuth: []
tags:
- name: Version Management
  description: Endpoints for retrieving, creating, and managing versions.
paths:
  /api/v1/version/id/{version_id}:
    get:
      tags:
      - Version Management
      summary: Get Version by ID
      description: Retrieve a specific Version based on its unique DealHub ID.
      operationId: getVersionById
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The unique identifier of the version.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
              examples:
                getVersionExample:
                  summary: Successful response
                  value:
                    name: Master v1
                    comment: ''
                    status: ACTIVE
                    version_id: '67657'
  /api/v1/version/name/{version_name}:
    get:
      tags:
      - Version Management
      summary: Get Version by Name
      description: Retrieve a specific Version based on its name.
      operationId: getVersionByName
      parameters:
      - name: version_name
        in: path
        required: true
        schema:
          type: string
          maxLength: 120
        description: The name of the version.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
              examples:
                getVersionExample:
                  summary: Successful response
                  value:
                    name: Master v1
                    comment: ''
                    status: ACTIVE
                    version_id: '67657'
  /api/v1/versions:
    get:
      tags:
      - Version Management
      summary: Get a List of Versions
      description: Retrieve a list of Versions, with an option to filter by status. If no parameters are provided, it returns all versions.
      operationId: getVersions
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - DRAFT
          - ACTIVE
          - DEACTIVATED
        description: Search for Version(s) based on status.
      responses:
        '200':
          description: Success. Returns a list of version objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Version'
              examples:
                getVersionsExample:
                  summary: Example list of versions
                  value:
                  - name: v3a
                    comment: ''
                    status: DEACTIVATED
                    version_id: 068DoObdli5GuF14
                  - name: msd6
                    comment: ''
                    status: DEACTIVATED
                    version_id: 0AjX3aABgLN9f8uG
  /api/v1/version/duplicate:
    post:
      tags:
      - Version Management
      summary: Duplicate a Version
      description: Asynchronously creates a new Version entity based on an existing one. This operation returns a `request_id` for tracking.
      operationId: duplicateVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DuplicateVersionRequest'
            examples:
              duplicateVersionExample:
                summary: Duplicate a version to a new instance
                value:
                  version_id: '765379899'
                  new_version_name: New Version
                  comment: Adding more BroadBand services
                  to_account_instance: Account abc
      responses:
        '200':
          description: Success. The duplication process has started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
              examples:
                asyncResponseExample:
                  summary: Successful response
                  value:
                    request_id: 4D114DAD97
  /api/v1/version/activate:
    post:
      tags:
      - Version Management
      summary: Activate a Version
      description: Asynchronously activates a `DRAFT` Version. This operation returns a `request_id` for tracking.
      operationId: activateVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateVersionRequest'
            examples:
              activateVersionExample:
                summary: Request to activate a version
                value:
                  version_id: '765379899'
      responses:
        '200':
          description: Success. The activation process has started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
              examples:
                asyncResponseExample:
                  summary: Successful response
                  value:
                    request_id: 4D114DAD97
components:
  schemas:
    ActivateVersionRequest:
      type: object
      required:
      - version_id
      properties:
        version_id:
          type: string
          maxLength: 16
          description: ID of the Version that should be activated.
    AsyncResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The ID of the asynchronous request for tracking.
    DuplicateVersionRequest:
      type: object
      required:
      - version_id
      - new_version_name
      properties:
        version_id:
          type: string
          maxLength: 16
          description: ID of the version that should be duplicated.
        new_version_name:
          type: string
          maxLength: 120
          description: Name for the new version.
        comment:
          type: string
          maxLength: 4000
          description: Comments for the newly created version.
        to_account_instance:
          type: string
          description: Instance name of the Account where the version should be duplicated to (e.g., for Sandbox to Production).
    Version:
      type: object
      properties:
        name:
          type: string
          description: Name of the version.
        comment:
          type: string
          description: Comment provided during version creation.
        status:
          type: string
          description: Status of the version.
        version_id:
          type: string
          description: The unique identifier of the version.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A secret token generated by a CPQ administrator.