Dealhubio Asynchronous Operations API

openapi: 3.2.0
info:
  title: Version Asynchronous Operations 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.
security:
- bearerAuth: []
tags:
- name: Asynchronous Operations
  description: Endpoints for tracking the status of asynchronous requests.
paths:
  /api/v1/request/{request_id}/status:
    get:
      tags:
      - Asynchronous Operations
      summary: Get Asynchronous Request Status
      description: Polls and retrieves the current status of a specific asynchronous request (e.g., duplicate version, activate version).
      operationId: getAsyncRequestStatus
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The ID of the asynchronous request.
      responses:
        '200':
          description: Success. Returns the current status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatus'
              examples:
                requestStatusExample:
                  summary: Example of a completed request status
                  value:
                    request_id: 4D114DAD97
                    status: done
                    error_description: ''
                    error_code: null
        '400':
          description: Bad Request. No asynchronous request was found matching the provided `request_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFoundExample:
                  summary: Request not found
                  value:
                    error: Entity (ID = 4D114DAD97) not found
                    code: 400
        '403':
          description: Unauthenticated. The `Authorization` token is missing, invalid, or does not match the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthenticatedExample:
                  summary: Unauthenticated
                  value:
                    error: Unauthenticated
                    code: 403
  /api/v1/request/{request_id}/summary:
    get:
      tags:
      - Asynchronous Operations
      summary: Get Asynchronous Request Execution Summary
      description: Retrieves a summary of a completed asynchronous process, including success, error, and warning counts. This is particularly useful for operations like product catalog uploads.
      operationId: getAsyncRequestSummary
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The ID of the asynchronous request.
      responses:
        '200':
          description: Success. Returns the execution summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestSummaryResponse'
              examples:
                requestSummaryExample:
                  summary: Example of a request summary with warnings
                  value:
                    status: Completed
                    summary:
                      success_count: 1
                      errors_count: 0
                      warnings:
                      - 'Missing currency in price item for SKU KY014X, using default currency: USD'
                      errors: []
        '400':
          description: Bad Request. No asynchronous request was found matching the provided `request_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFoundExample:
                  summary: Request not found
                  value:
                    error: Entity (ID = 4D114DAD97) not found
                    code: 400
        '403':
          description: Unauthenticated. The `Authorization` token is missing, invalid, or does not match the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthenticatedExample:
                  summary: Unauthenticated
                  value:
                    error: Unauthenticated
                    code: 403
components:
  schemas:
    RequestSummaryResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - In Progress
          - Completed
          - Error
          description: The status of the asynchronous request.
        summary:
          $ref: '#/components/schemas/RequestSummary'
    RequestStatus:
      type: object
      properties:
        request_id:
          type: string
          description: ID of the asynchronous request.
        status:
          type: string
          enum:
          - in-progress
          - done
          - failed
          - queued
          description: Status of the asynchronous request.
        error_description:
          type: string
          description: Description of the error if the status is 'failed'.
        error_code:
          type: string
          description: Code of the error if the status is 'failed'.
    ErrorResponse:
      type: object
      description: A generic error response. The specific message and code vary based on the context.
      properties:
        error:
          type: string
          description: Human-readable error message describing the issue.
        code:
          type: integer
          description: HTTP status code.
    RequestSummary:
      type: object
      properties:
        success_count:
          type: integer
          description: The number of successfully processed records.
        errors_count:
          type: integer
          description: The number of records that could not be processed.
        warnings:
          type: array
          items:
            type: string
            description: List of warnings that occurred during execution.
        errors:
          type: array
          items:
            type: string
          description: List of errors that occurred during execution.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A secret token generated by a CPQ administrator.
x-provenance:
  method: searched
  source: https://developers.dealhub.io/reference
  harvested: '2026-10-22'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.dealhub.io/reference/activateversion.md
  - https://developers.dealhub.io/reference/deleteallproducts.md
  - https://developers.dealhub.io/reference/deletefromproducthierarchy.md
  - https://developers.dealhub.io/reference/deleteproductsbysku.md
  - https://developers.dealhub.io/reference/duplicateversion.md
  - https://developers.dealhub.io/reference/exportplaybookdata.md
  - https://developers.dealhub.io/reference/extractproductsexcel.md
  - https://developers.dealhub.io/reference/getasyncrequeststatus.md
  - https://developers.dealhub.io/reference/getasyncrequestsummary.md
  - https://developers.dealhub.io/reference/getgeneratequotetemplate.md
  - https://developers.dealhub.io/reference/getproductcatalog.md
  - https://developers.dealhub.io/reference/getproducthierarchy.md
  - https://developers.dealhub.io/reference/getproductsbysku.md
  - https://developers.dealhub.io/reference/getversionbyid.md
  - https://developers.dealhub.io/reference/getversionbyname.md
  - https://developers.dealhub.io/reference/getversionproducts.md
  - https://developers.dealhub.io/reference/getversions.md
  - https://developers.dealhub.io/reference/updateproductcatalog.md
  - https://developers.dealhub.io/reference/updateproducthierarchy.md
  - https://developers.dealhub.io/reference/uploadproductcatalog.md
  merge:
    pages: 20
    deduped: 79
    conflicts_kept_first: 0