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
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commvault/refs/heads/main/openapi/commvault-rest-openapi.yml