openapi: 3.1.0 info: title: Commvault REST API description: >- The Commvault REST API provides programmatic access to Commvault data protection and management operations, including clients, agents, subclients, backup jobs, restore jobs, storage policies, schedules, and reporting. This API uses XML or JSON request and response bodies and supports token-based authentication via login credentials or SAML-based SSO. version: v2 contact: name: Commvault Support url: https://www.commvault.com/support termsOfService: https://www.commvault.com/terms-of-use externalDocs: description: Commvault REST API Documentation url: https://documentation.commvault.com/v11/essential/rest_api_overview.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: Agents description: Manage backup agents installed on clients - name: Alerts description: Manage alerts and notification configurations - name: Authentication description: Login and token management operations - name: Clients description: Manage clients (servers, workstations, virtual machines) - name: Jobs description: View and manage backup, restore, and administrative jobs - name: Plans description: Manage server plans for data protection - name: Schedule Policies description: Manage schedule policies for automated operations - name: Storage Policies description: Manage storage policies and copies - name: Subclients description: Manage subclients that define backup content - name: Users description: Manage Commvault users and user groups security: - authToken: [] paths: /Login: post: operationId: login summary: Commvault Authenticate and obtain auth token description: >- Authenticates a user with username and password credentials and returns an authentication token (QSDK token) for subsequent API requests. The token must be included in the Authtoken header of all subsequent requests. tags: - Authentication requestBody: required: true content: application/json: schema: type: object required: - username - password properties: username: type: string description: Commvault username password: type: string description: Base64-encoded password format: password responses: '200': description: Authentication successful content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '401': description: Invalid credentials security: [] /Logout: post: operationId: logout summary: Commvault Invalidate auth token description: >- Logs out the current user session and invalidates the authentication token. tags: - Authentication responses: '200': description: Logout successful /Client: get: operationId: listClients summary: Commvault List all clients description: >- Retrieves a list of all clients registered in the CommServe, including servers, workstations, laptop clients, and virtual machine proxies. tags: - Clients responses: '200': description: List of clients content: application/json: schema: type: object properties: clientProperties: type: array items: $ref: '#/components/schemas/Client' '401': description: Unauthorized /Client/{clientId}: get: operationId: getClient summary: Commvault Get client details description: >- Retrieves detailed properties of a specific client including installed agents, network configuration, and activity control settings. tags: - Clients parameters: - $ref: '#/components/parameters/clientId' responses: '200': description: Client details content: application/json: schema: type: object properties: clientProperties: type: array items: $ref: '#/components/schemas/Client' '401': description: Unauthorized '404': description: Client not found put: operationId: updateClient summary: Commvault Update client properties description: >- Updates properties of a specific client such as display name, activity control, or network settings. tags: - Clients parameters: - $ref: '#/components/parameters/clientId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateClientRequest' responses: '200': description: Client updated successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '400': description: Invalid request '401': description: Unauthorized '404': description: Client not found delete: operationId: deleteClient summary: Commvault Retire or delete a client description: >- Retires or deletes a client from the CommServe. This removes the client configuration but may preserve backup data based on retention policies. tags: - Clients parameters: - $ref: '#/components/parameters/clientId' responses: '200': description: Client deleted successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '401': description: Unauthorized '404': description: Client not found /Agent: get: operationId: listAgents summary: Commvault List agents for a client description: >- Retrieves a list of all agents (iDataAgents) installed on a specific client. Agents represent the backup module for a particular application type (File System, SQL, Exchange, etc.). tags: - Agents parameters: - name: clientId in: query required: true description: Client ID to list agents for schema: type: integer responses: '200': description: List of agents content: application/json: schema: type: object properties: agentProperties: type: array items: $ref: '#/components/schemas/Agent' '401': description: Unauthorized /Subclient: get: operationId: listSubclients summary: Commvault List subclients description: >- Retrieves a list of subclients for a given client and agent. Subclients define the specific content (files, databases, mailboxes) to be backed up and their associated storage and schedule policies. tags: - Subclients parameters: - name: clientId in: query required: true description: Client ID schema: type: integer - name: applicationId in: query required: false description: Application/agent type ID schema: type: integer responses: '200': description: List of subclients content: application/json: schema: type: object properties: subClientProperties: type: array items: $ref: '#/components/schemas/Subclient' '401': description: Unauthorized /Subclient/{subclientId}: get: operationId: getSubclient summary: Commvault Get subclient details description: >- Retrieves detailed properties of a specific subclient, including content paths, filters, storage policy association, and schedule configuration. tags: - Subclients parameters: - $ref: '#/components/parameters/subclientId' responses: '200': description: Subclient details content: application/json: schema: type: object properties: subClientProperties: type: array items: $ref: '#/components/schemas/Subclient' '401': description: Unauthorized '404': description: Subclient not found /Job: get: operationId: listJobs summary: Commvault List jobs description: >- Retrieves a list of jobs with optional filtering by status, type, client, and time range. Returns both active and completed backup, restore, and administrative jobs. tags: - Jobs parameters: - name: clientId in: query required: false description: Filter jobs by client ID schema: type: integer - name: jobFilter in: query required: false description: Filter by job status (e.g., Running, Completed, Failed) schema: type: string enum: - Running - Waiting - Pending - Completed - Failed - Killed - Suspended - name: limit in: query required: false description: Maximum number of jobs to return schema: type: integer default: 100 - name: lookupTime in: query required: false description: Time range in hours to look back for jobs schema: type: integer responses: '200': description: List of jobs content: application/json: schema: type: object properties: jobs: type: array items: $ref: '#/components/schemas/Job' totalRecordsWithoutPaging: type: integer description: Total number of matching jobs '401': description: Unauthorized /Job/{jobId}: get: operationId: getJob summary: Commvault Get job details description: >- Retrieves detailed information about a specific job, including its status, progress, start and end times, data transferred, and any failure reasons. tags: - Jobs parameters: - $ref: '#/components/parameters/jobId' responses: '200': description: Job details content: application/json: schema: type: object properties: jobs: type: array items: $ref: '#/components/schemas/Job' '401': description: Unauthorized '404': description: Job not found /Job/{jobId}/action/kill: post: operationId: killJob summary: Commvault Kill a running job description: >- Terminates a currently running or pending job. The job will be marked as killed and any partial data may be retained. tags: - Jobs parameters: - $ref: '#/components/parameters/jobId' responses: '200': description: Job killed successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '401': description: Unauthorized '404': description: Job not found /Job/{jobId}/action/suspend: post: operationId: suspendJob summary: Commvault Suspend a running job description: >- Suspends a currently running job. The job can be resumed later from where it was paused. tags: - Jobs parameters: - $ref: '#/components/parameters/jobId' responses: '200': description: Job suspended successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '401': description: Unauthorized '404': description: Job not found /Job/{jobId}/action/resume: post: operationId: resumeJob summary: Commvault Resume a suspended job description: >- Resumes a previously suspended job from where it was paused. tags: - Jobs parameters: - $ref: '#/components/parameters/jobId' responses: '200': description: Job resumed successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '401': description: Unauthorized '404': description: Job not found /StoragePolicy: get: operationId: listStoragePolicies summary: Commvault List storage policies description: >- Retrieves a list of all storage policies configured in the CommServe. Storage policies define where backup data is stored and how it is managed across primary, secondary, and tertiary storage tiers. tags: - Storage Policies responses: '200': description: List of storage policies content: application/json: schema: type: object properties: policies: type: array items: $ref: '#/components/schemas/StoragePolicy' '401': description: Unauthorized /StoragePolicy/{storagePolicyId}: get: operationId: getStoragePolicy summary: Commvault Get storage policy details description: >- Retrieves detailed configuration of a specific storage policy, including its copies, retention rules, deduplication settings, and associated media agents. tags: - Storage Policies parameters: - $ref: '#/components/parameters/storagePolicyId' responses: '200': description: Storage policy details content: application/json: schema: $ref: '#/components/schemas/StoragePolicy' '401': description: Unauthorized '404': description: Storage policy not found /SchedulePolicy: get: operationId: listSchedulePolicies summary: Commvault List schedule policies description: >- Retrieves a list of all schedule policies defined in the CommServe. Schedule policies automate backup, auxiliary copy, and other operations on a recurring basis. tags: - Schedule Policies responses: '200': description: List of schedule policies content: application/json: schema: type: object properties: taskDetail: type: array items: $ref: '#/components/schemas/SchedulePolicy' '401': description: Unauthorized /AlertRule: get: operationId: listAlerts summary: Commvault List alert rules description: >- Retrieves a list of configured alert rules. Alerts notify administrators of important events such as job failures, storage thresholds, and security events. tags: - Alerts responses: '200': description: List of alert rules content: application/json: schema: type: object properties: alertList: type: array items: $ref: '#/components/schemas/Alert' '401': description: Unauthorized /User: get: operationId: listUsers summary: Commvault List users description: >- Retrieves a list of all Commvault users, including local and externally authenticated users, their roles, and associated user groups. tags: - Users responses: '200': description: List of users content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' '401': description: Unauthorized /User/{userId}: get: operationId: getUser summary: Commvault Get user details description: >- Retrieves detailed properties of a specific user, including associated security roles, user groups, and email configuration. tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: User details content: application/json: schema: $ref: '#/components/schemas/User' '401': description: Unauthorized '404': description: User not found /V4/ServerPlan: get: operationId: listPlans summary: Commvault List server plans description: >- Retrieves a list of all server plans. Plans provide a simplified approach to data protection by combining storage, schedule, and retention settings into a single configuration entity. tags: - Plans responses: '200': description: List of server plans content: application/json: schema: type: object properties: plans: type: array items: $ref: '#/components/schemas/Plan' '401': description: Unauthorized post: operationId: createPlan summary: Commvault Create a server plan description: >- Creates a new server plan with specified backup destinations, schedule, and retention settings. tags: - Plans requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePlanRequest' responses: '200': description: Plan created successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '400': description: Invalid request '401': description: Unauthorized /V4/ServerPlan/{planId}: get: operationId: getPlan summary: Commvault Get server plan details description: >- Retrieves the detailed configuration of a specific server plan, including its backup destinations, RPO schedules, and retention rules. tags: - Plans parameters: - $ref: '#/components/parameters/planId' responses: '200': description: Plan details content: application/json: schema: $ref: '#/components/schemas/Plan' '401': description: Unauthorized '404': description: Plan not found put: operationId: updatePlan summary: Commvault Update a server plan description: >- Updates the configuration of an existing server plan. tags: - Plans parameters: - $ref: '#/components/parameters/planId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePlanRequest' responses: '200': description: Plan updated successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '400': description: Invalid request '401': description: Unauthorized '404': description: Plan not found delete: operationId: deletePlan summary: Commvault Delete a server plan description: >- Deletes an existing server plan. Plans that are associated with active subclients cannot be deleted. tags: - Plans parameters: - $ref: '#/components/parameters/planId' responses: '200': description: Plan deleted successfully content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '401': description: Unauthorized '404': description: Plan not found /CreateTask: post: operationId: createBackupTask summary: Commvault Run a backup job description: >- Initiates a backup job for a specified subclient. Supports full, incremental, differential, and synthetic full backup levels. tags: - Jobs requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BackupTaskRequest' responses: '200': description: Backup job created content: application/json: schema: type: object properties: jobIds: type: array items: type: string description: IDs of created backup jobs '400': description: Invalid request '401': description: Unauthorized /retrieveToClient: post: operationId: createRestoreTask summary: Commvault Run a restore job description: >- Initiates a restore operation to recover backed-up data to the original or an alternate location. Supports in-place restore, out-of-place restore, and cross-platform restore. tags: - Jobs requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RestoreTaskRequest' responses: '200': description: Restore job created content: application/json: schema: type: object properties: jobIds: type: array items: type: string description: IDs of created restore jobs '400': description: Invalid request '401': description: Unauthorized components: securitySchemes: authToken: type: apiKey in: header name: Authtoken description: >- QSDK authentication token obtained from the Login endpoint. Include this token in all subsequent API requests. parameters: clientId: name: clientId in: path required: true description: Unique identifier for the client schema: type: integer subclientId: name: subclientId in: path required: true description: Unique identifier for the subclient schema: type: integer jobId: name: jobId in: path required: true description: Unique identifier for the job schema: type: integer storagePolicyId: name: storagePolicyId in: path required: true description: Unique identifier for the storage policy schema: type: integer userId: name: userId in: path required: true description: Unique identifier for the user schema: type: integer planId: name: planId in: path required: true description: Unique identifier for the server plan schema: type: integer schemas: LoginResponse: type: object properties: token: type: string description: Authentication token for subsequent API requests userId: type: integer description: ID of the authenticated user userName: type: string description: Username of the authenticated user aliasName: type: string description: Alias name of the authenticated user loginAttempts: type: integer description: Number of login attempts remaining remainingLockTime: type: integer description: Time remaining before account lockout expires Client: type: object properties: client: type: object properties: clientId: type: integer description: Unique client identifier clientName: type: string description: Display name of the client hostName: type: string description: Network hostname of the client displayName: type: string description: User-friendly display name clientProps: type: object properties: activityControl: type: object properties: enableBackup: type: boolean description: Whether backup is enabled enableRestore: type: boolean description: Whether restore is enabled contentIndexingProps: type: object description: Content indexing configuration UpdateClientRequest: type: object properties: clientProperties: type: object properties: client: type: object properties: clientName: type: string description: New display name for the client clientProps: type: object properties: activityControl: type: object properties: enableBackup: type: boolean enableRestore: type: boolean Agent: type: object properties: idaEntity: type: object properties: applicationId: type: integer description: Application type identifier applicationName: type: string description: Name of the agent (e.g., File System, SQL Server) clientId: type: integer description: Parent client ID clientName: type: string description: Parent client name Subclient: type: object properties: subClientEntity: type: object properties: subclientId: type: integer description: Unique subclient identifier subclientName: type: string description: Name of the subclient clientId: type: integer description: Parent client ID clientName: type: string description: Parent client name appName: type: string description: Agent/application name commonProperties: type: object properties: storageDevice: type: object properties: dataBackupStoragePolicy: type: object properties: storagePolicyName: type: string description: Associated storage policy name Job: type: object properties: jobSummary: type: object properties: jobId: type: integer description: Unique job identifier jobType: type: string description: Type of job (Backup, Restore, etc.) status: type: string description: Current job status enum: - Running - Waiting - Pending - Completed - Completed w/ one or more errors - Completed w/ one or more warnings - Failed - Killed - Suspended subclient: type: object properties: subclientName: type: string clientName: type: string backupLevel: type: string description: Backup level (Full, Incremental, etc.) percentComplete: type: integer description: Job completion percentage minimum: 0 maximum: 100 startTime: type: integer description: Job start time as Unix timestamp endTime: type: integer description: Job end time as Unix timestamp sizeOfBackup: type: integer description: Size of backed up data in bytes sizeOfMediaOnDisk: type: integer description: Size of data written to media StoragePolicy: type: object properties: storagePolicyId: type: integer description: Unique storage policy identifier storagePolicyName: type: string description: Name of the storage policy copies: type: array items: type: object properties: copyName: type: string description: Name of the storage policy copy copyType: type: string description: Type of copy (Primary, Secondary, etc.) retentionRules: type: object properties: retainBackupDataForDays: type: integer description: Number of days to retain backup data retainBackupDataForCycles: type: integer description: Number of cycles to retain backup data SchedulePolicy: type: object properties: taskId: type: integer description: Unique schedule policy identifier taskName: type: string description: Name of the schedule policy taskType: type: string description: Type of task subTasks: type: array items: type: object properties: subTaskName: type: string description: Name of the sub-task operationType: type: string description: Operation type (Backup, Restore, etc.) pattern: type: object properties: freq_type: type: string description: Frequency type (Daily, Weekly, Monthly) active_start_time: type: integer description: Schedule start time Alert: type: object properties: id: type: integer description: Unique alert identifier name: type: string description: Alert rule name alertType: type: integer description: Type of alert severity: type: string description: Alert severity level enum: - Information - Warning - Critical criteria: type: object description: Conditions that trigger the alert User: type: object properties: userEntity: type: object properties: userId: type: integer description: Unique user identifier userName: type: string description: Username email: type: string format: email description: User email address description: type: string description: User description enabled: type: boolean description: Whether the user account is enabled associatedUserGroups: type: array items: type: object properties: userGroupName: type: string description: Name of the user group Plan: type: object properties: plan: type: object properties: planId: type: integer description: Unique plan identifier planName: type: string description: Name of the server plan storage: type: object properties: storagePolicyName: type: string description: Associated storage policy name schedule: type: object properties: rpoInMinutes: type: integer description: Recovery Point Objective in minutes retention: type: object properties: retainBackupDataForDays: type: integer description: Days to retain backup data CreatePlanRequest: type: object required: - planName properties: planName: type: string description: Name for the new server plan backupDestinations: type: array items: type: object properties: backupDestinationName: type: string storagePolicyName: type: string rpoInMinutes: type: integer description: Recovery Point Objective in minutes BackupTaskRequest: type: object properties: taskInfo: type: object properties: subTasks: type: array items: type: object properties: subTask: type: object properties: operationType: type: string enum: - BACKUP options: type: object properties: backupOpts: type: object properties: backupLevel: type: string enum: - FULL - INCREMENTAL - DIFFERENTIAL - SYNTHETIC_FULL associations: type: array items: type: object properties: subclientName: type: string clientName: type: string appName: type: string RestoreTaskRequest: type: object properties: taskInfo: type: object properties: subTasks: type: array items: type: object properties: subTask: type: object properties: operationType: type: string enum: - RESTORE options: type: object properties: restoreOptions: type: object properties: destination: type: object properties: destClient: type: object properties: clientName: type: string destinationPath: type: string fileOption: type: object properties: sourceItem: type: array items: type: string description: Paths of items to restore GenericResponse: type: object properties: errorCode: type: integer description: Error code (0 indicates success) errorMessage: type: string description: Human-readable error or success message