Commvault Automation API

openapi: 3.1.0
info:
  title: Commvault Automation API
  description: >-
    API for automating Commvault workflows, job scheduling, and policy
    management. Enables programmatic creation and execution of custom
    workflows, management of schedule policies, and configuration of
    automated operations for data protection environments.
  version: v2
  contact:
    name: Commvault Support
    url: https://www.commvault.com/support
  termsOfService: https://www.commvault.com/terms-of-use
externalDocs:
  description: Commvault Automation API Documentation
  url: https://documentation.commvault.com/v11/essential/rest_api_automation.html
servers:
  - url: https://{webserver}/webconsole/api
    description: Commvault Web Server
    variables:
      webserver:
        default: webconsole.example.com
        description: Hostname of the Commvault Web Server
tags:
  - name: Operations
    description: Trigger and monitor automated operations
  - name: Policies
    description: Manage data protection policies
  - name: Schedules
    description: Manage job schedules and schedule policies
  - name: Scripts
    description: Manage and execute automation scripts
  - name: Workflows
    description: Create, manage, and execute automation workflows
security:
  - authToken: []
paths:
  /Workflow:
    get:
      operationId: listWorkflows
      summary: Commvault List all workflows
      description: >-
        Retrieves a list of all workflows defined in the CommServe,
        including built-in and custom workflows. Workflows automate
        multi-step processes such as provisioning, disaster recovery
        drills, and data migration.
      tags:
        - Workflows
      responses:
        '200':
          description: List of workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  container:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
  /Workflow/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Commvault Get workflow details
      description: >-
        Retrieves the detailed definition of a specific workflow,
        including its activities, inputs, conditions, and execution
        history.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/workflowId'
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
    delete:
      operationId: deleteWorkflow
      summary: Commvault Delete a workflow
      description: >-
        Deletes a custom workflow from the CommServe. Built-in workflows
        cannot be deleted.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/workflowId'
      responses:
        '200':
          description: Workflow deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
  /Workflow/{workflowName}/Action/Execute:
    post:
      operationId: executeWorkflow
      summary: Commvault Execute a workflow
      description: >-
        Triggers the execution of a workflow by name. Input parameters
        can be provided in the request body to customize the workflow
        execution. Returns a job ID for tracking the execution.
      tags:
        - Workflows
      parameters:
        - name: workflowName
          in: path
          required: true
          description: Name of the workflow to execute
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowExecuteRequest'
      responses:
        '200':
          description: Workflow execution started
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: integer
                    description: Job ID tracking the workflow execution
                  errorCode:
                    type: integer
                  errorMessage:
                    type: string
        '400':
          description: Invalid input parameters
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
  /Workflow/Deploy:
    post:
      operationId: deployWorkflow
      summary: Commvault Deploy a workflow definition
      description: >-
        Deploys a new workflow or updates an existing workflow definition
        in the CommServe. The workflow XML definition is provided in the
        request body.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: Workflow XML definition
      responses:
        '200':
          description: Workflow deployed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Invalid workflow definition
        '401':
          description: Unauthorized
  /Task:
    get:
      operationId: listSchedules
      summary: Commvault List all schedules
      description: >-
        Retrieves a list of all scheduled tasks configured in the
        CommServe, including backup schedules, auxiliary copy schedules,
        and administrative operation schedules.
      tags:
        - Schedules
      parameters:
        - name: taskType
          in: query
          required: false
          description: Filter by task type
          schema:
            type: string
            enum:
              - QR_BACKUP
              - QR_RESTORE
              - QR_AUX_COPY
              - QR_ADMIN
              - QR_DATA_AGING
      responses:
        '200':
          description: List of scheduled tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDetail:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduledTask'
        '401':
          description: Unauthorized
  /Task/{taskId}:
    get:
      operationId: getSchedule
      summary: Commvault Get schedule details
      description: >-
        Retrieves detailed configuration of a specific scheduled task,
        including its schedule pattern, associated entities, and
        execution options.
      tags:
        - Schedules
      parameters:
        - $ref: '#/components/parameters/taskId'
      responses:
        '200':
          description: Scheduled task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTask'
        '401':
          description: Unauthorized
        '404':
          description: Scheduled task not found
    put:
      operationId: updateSchedule
      summary: Commvault Update a schedule
      description: >-
        Updates the configuration of an existing scheduled task,
        including its schedule pattern, enabled state, and execution
        options.
      tags:
        - Schedules
      parameters:
        - $ref: '#/components/parameters/taskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
      responses:
        '200':
          description: Schedule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Scheduled task not found
    delete:
      operationId: deleteSchedule
      summary: Commvault Delete a schedule
      description: >-
        Deletes a scheduled task from the CommServe.
      tags:
        - Schedules
      parameters:
        - $ref: '#/components/parameters/taskId'
      responses:
        '200':
          description: Schedule deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          description: Unauthorized
        '404':
          description: Scheduled task not found
  /Task/{taskId}/Action/Enable:
    post:
      operationId: enableSchedule
      summary: Commvault Enable a schedule
      description: Enables a previously disabled scheduled task.
      tags:
        - Schedules
      parameters:
        - $ref: '#/components/parameters/taskId'
      responses:
        '200':
          description: Schedule enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          description: Unauthorized
        '404':
          description: Scheduled task not found
  /Task/{taskId}/Action/Disable:
    post:
      operationId: disableSchedule
      summary: Commvault Disable a schedule
      description: >-
        Disables a scheduled task, preventing it from executing until
        re-enabled.
      tags:
        - Schedules
      parameters:
        - $ref: '#/components/parameters/taskId'
      responses:
        '200':
          description: Schedule disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          description: Unauthorized
        '404':
          description: Scheduled task not found
  /V4/CommcellGlobalFilter:
    get:
      operationId: getGlobalFilters
      summary: Commvault Get global data protection filters
      description: >-
        Retrieves the global exclusion filters applied to all backup
        operations, such as temporary file patterns, operating system
        cache directories, and other commonly excluded content.
      tags:
        - Policies
      responses:
        '200':
          description: Global filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  globalFiltersInfo:
                    type: object
                    properties:
                      windowsFilters:
                        type: array
                        items:
                          type: string
                      unixFilters:
                        type: array
                        items:
                          type: string
        '401':
          description: Unauthorized
    put:
      operationId: updateGlobalFilters
      summary: Commvault Update global data protection filters
      description: Updates the global exclusion filters for backup operations.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                globalFiltersInfo:
                  type: object
                  properties:
                    windowsFilters:
                      type: array
                      items:
                        type: string
                    unixFilters:
                      type: array
                      items:
                        type: string
      responses:
        '200':
          description: Global filters updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /QCommand/qoperation:
    post:
      operationId: executeQCommand
      summary: Commvault Execute a qcommand operation
      description: >-
        Executes an arbitrary Commvault command-line (qcommand)
        operation through the REST API. This provides programmatic
        access to operations that may not have dedicated REST endpoints.
      tags:
        - Operations
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: XML command to execute
      responses:
        '200':
          description: Command executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Invalid command
        '401':
          description: Unauthorized
  /Script:
    get:
      operationId: listScripts
      summary: Commvault List automation scripts
      description: >-
        Retrieves a list of all automation scripts registered in the
        CommServe, including pre/post backup scripts and custom
        automation scripts.
      tags:
        - Scripts
      responses:
        '200':
          description: List of scripts
          content:
            application/json:
              schema:
                type: object
                properties:
                  scripts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Script'
        '401':
          description: Unauthorized
  /Script/{scriptId}:
    get:
      operationId: getScript
      summary: Commvault Get script details
      description: >-
        Retrieves the details of a specific automation script, including
        its content, associated triggers, and execution history.
      tags:
        - Scripts
      parameters:
        - $ref: '#/components/parameters/scriptId'
      responses:
        '200':
          description: Script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
        '401':
          description: Unauthorized
        '404':
          description: Script not found
  /Script/{scriptId}/Action/Execute:
    post:
      operationId: executeScript
      summary: Commvault Execute an automation script
      description: >-
        Triggers the execution of an automation script with optional
        input parameters.
      tags:
        - Scripts
      parameters:
        - $ref: '#/components/parameters/scriptId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                inputParameters:
                  type: object
                  additionalProperties:
                    type: string
                  description: Key-value pairs of input parameters
      responses:
        '200':
          description: Script execution started
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: integer
                    description: Job ID tracking the script execution
                  errorCode:
                    type: integer
                  errorMessage:
                    type: string
        '400':
          description: Invalid input parameters
        '401':
          description: Unauthorized
        '404':
          description: Script not found
components:
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authtoken
      description: >-
        QSDK authentication token obtained from the Login endpoint.
  parameters:
    workflowId:
      name: workflowId
      in: path
      required: true
      description: Unique identifier for the workflow
      schema:
        type: integer
    taskId:
      name: taskId
      in: path
      required: true
      description: Unique identifier for the scheduled task
      schema:
        type: integer
    scriptId:
      name: scriptId
      in: path
      required: true
      description: Unique identifier for the automation script
      schema:
        type: integer
  schemas:
    Workflow:
      type: object
      properties:
        workflowId:
          type: integer
          description: Unique workflow identifier
        workflowName:
          type: string
          description: Name of the workflow
        description:
          type: string
          description: Description of the workflow
        enabled:
          type: boolean
          description: Whether the workflow is enabled
        workflowType:
          type: string
          description: Type of workflow
          enum:
            - BuiltIn
            - Custom
        activities:
          type: array
          items:
            type: object
            properties:
              activityName:
                type: string
                description: Name of the activity
              activityType:
                type: string
                description: Type of activity
              sequence:
                type: integer
                description: Execution order
        inputs:
          type: array
          items:
            type: object
            properties:
              inputName:
                type: string
                description: Name of the input parameter
              inputType:
                type: string
                description: Data type of the input
              required:
                type: boolean
                description: Whether the input is required
              defaultValue:
                type: string
                description: Default value if not provided
    WorkflowExecuteRequest:
      type: object
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              inputName:
                type: string
                description: Name of the input parameter
              inputValue:
                type: string
                description: Value for the input parameter
    ScheduledTask:
      type: object
      properties:
        taskId:
          type: integer
          description: Unique task identifier
        taskName:
          type: string
          description: Name of the scheduled task
        taskType:
          type: string
          description: Type of scheduled operation
          enum:
            - QR_BACKUP
            - QR_RESTORE
            - QR_AUX_COPY
            - QR_ADMIN
            - QR_DATA_AGING
        enabled:
          type: boolean
          description: Whether the schedule is enabled
        subTasks:
          type: array
          items:
            type: object
            properties:
              subTaskName:
                type: string
              operationType:
                type: string
              pattern:
                $ref: '#/components/schemas/SchedulePattern'
        associations:
          type: array
          items:
            type: object
            properties:
              clientName:
                type: string
              subclientName:
                type: string
              appName:
                type: string
    UpdateScheduleRequest:
      type: object
      properties:
        taskInfo:
          type: object
          properties:
            taskName:
              type: string
              description: Updated task name
            enabled:
              type: boolean
              description: Enable or disable the schedule
            subTasks:
              type: array
              items:
                type: object
                properties:
                  pattern:
                    $ref: '#/components/schemas/SchedulePattern'
    SchedulePattern:
      type: object
      properties:
        freq_type:
          type: string
          description: Frequency type
          enum:
            - ONE_TIME
            - DAILY
            - WEEKLY
            - MONTHLY
            - CONTINUOUS
            - AUTOMATIC
        active_start_time:
          type: integer
          description: Schedule start time in seconds since midnight
        active_end_time:
          type: integer
          description: Schedule end time in seconds since midnight
        freq_interval:
          type: integer
          description: Frequency interval value
        freq_recurrence_factor:
          type: integer
          description: Recurrence factor (e.g., every N days/weeks)
        daysOfWeek:
          type: array
          items:
            type: string
            enum:
              - Sunday
              - Monday
              - Tuesday
              - Wednesday
              - Thursday
              - Friday
              - Saturday
          description: Days of the week for weekly schedules
    Script:
      type: object
      properties:
        scriptId:
          type: integer
          description: Unique script identifier
        scriptName:
          type: string
          description: Name of the script
        description:
          type: string
          description: Description of the script
        scriptType:
          type: string
          description: Script language type
          enum:
            - Python
            - PowerShell
            - Shell
            - Batch
        content:
          type: string
          description: Script content/source code
        enabled:
          type: boolean
          description: Whether the script is enabled
    GenericResponse:
      type: object
      properties:
        errorCode:
          type: integer
          description: Error code (0 indicates success)
        errorMessage:
          type: string
          description: Human-readable error or success message