Veeam Backup & Replication 13
REST API Reference
Related documents

High Availability (HA) Cluster

The High Availability (HA) Cluster section defines operations for configuring and managing a High Availability cluster of backup servers. You can get the cluster configuration, create, edit and delete the cluster, perform switchover and failover between cluster nodes.

Get High Availability Cluster

The HTTP GET request to the /api/v1/highAvailabilityCluster endpoint gets the High Availability cluster configuration record.

Available to: Backup Administrator, Backup Operator, Restore Operator, Backup Viewer.

SecurityBearer
Request
header Parameters
x-api-version
required
string
Default: 1.3-rev2

Version and revision of the client REST API. Must be in the following format: <version>-<revision>.

Responses
200

OK

400

Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.

401

Unauthorized. The authorization header has been expected but not found (or found but is expired).

403

Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.

500

Internal server error. The request has been received but could not be completed because of an internal error at the server side.

get/api/v1/highAvailabilityCluster
Request samples 
Response samples 
application/json
{
  • "id": "1f7c2d90-4ab8-4e21-9d3c-7b5e8a0f6c14",
  • "primaryNode": {
    },
  • "secondaryNode": {
    },
  • "name": "ha-cluster-01",
  • "clusterEndpoint": "172.24.29.165",
  • "clusterDnsName": "ha-cluster-01.tech.local",
  • "isCrossSubnetMode": false,
  • "states": {
    }
}
Create High Availability Cluster
The HTTP POST request to the /api/v1/highAvailabilityCluster endpoint creates a High Availability cluster.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
primaryNodeIpAddress
required
string
Primary node IP address.


 
secondaryNodeIpAddress
required
string
Secondary node IP address.


 
secondaryNodeCredentialsId
required
string <uuid> 
Secondary node credentials ID.


 
clusterDnsName
required
string
Cluster DNS name.


 
required
object (HaCertificateUploadSpec) 
PEM certificate settings for the HA cluster.


 
clusterEndpoint
string
Cluster IP address.


 
isCrossSubnetMode
boolean
If true, the cluster is created in cross-subnet mode.


 
primaryNodeExternalEndpoint
string
External endpoint of the primary node. Required when isCrossSubnetMode is true.


 
secondaryNodeExternalEndpoint
string
External endpoint of the secondary node. Required when isCrossSubnetMode is true.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/highAvailabilityCluster
Request samples 
application/json
{
  • "primaryNodeIpAddress": "172.24.29.163",
  • "secondaryNodeIpAddress": "172.24.29.164",
  • "secondaryNodeCredentialsId": "0a3b8d5f-1c24-4f9e-9b71-2e6c4d8a1f30",
  • "clusterEndpoint": "172.24.29.165",
  • "clusterDnsName": "ha-cluster-01.tech.local",
  • "certificate": {
    },
  • "isCrossSubnetMode": false,
  • "primaryNodeExternalEndpoint": "172.24.29.163:9419",
  • "secondaryNodeExternalEndpoint": "172.24.29.164:9419"
}
Response samples 
application/json
{
  • "sessionType": "Infrastructure",
  • "state": "Working",
  • "id": "5b2e4c61-8d39-4f72-a1b5-6e7c0d3f8a29",
  • "name": "Infrastructure Item Saving",
  • "jobId": "5b2e4c61-8d39-4f72-a1b5-6e7c0d3f8a29",
  • "creationTime": "2026-07-03T12:00:12+02:00",
  • "progressPercent": 0,
  • "result": {
    },
  • "usn": 2260,
  • "initiatedBy": "veeamadmin",
  • "originalSessionId": "5b2e4c61-8d39-4f72-a1b5-6e7c0d3f8a29"
}
Delete High Availability Cluster
The HTTP DELETE request to the /api/v1/highAvailabilityCluster endpoint removes the High Availability cluster configuration. This is an asynchronous operation that returns a session for tracking progress.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


delete/api/v1/highAvailabilityCluster
Request samples 
Response samples 
application/json
{
  • "sessionType": "InfrastructureItemDeletion",
  • "state": "Working",
  • "id": "7d4f6a82-9e51-4b83-92d6-8f0a1e5b9c37",
  • "name": "Infrastructure Item Deletion",
  • "jobId": "00000000-0000-0000-0000-000000000000",
  • "creationTime": "2026-07-03T12:10:45+02:00",
  • "progressPercent": 0,
  • "result": {
    },
  • "usn": 2295,
  • "initiatedBy": "veeamadmin",
  • "originalSessionId": "7d4f6a82-9e51-4b83-92d6-8f0a1e5b9c37"
}
Edit High Availability Cluster Settings
The HTTP POST request to the /api/v1/highAvailabilityCluster/changeCluster endpoint edits a High Availability cluster. This is an asynchronous operation that returns a session for tracking progress.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
clusterEndpoint
string
Cluster IP address.


 
clusterDnsName
string
Cluster DNS name.


 
primaryNodeExternalEndpoint
string
External endpoint of the primary node. Used in cross-subnet mode.


 
secondaryNodeExternalEndpoint
string
External endpoint of the secondary node. Used in cross-subnet mode.


 
Responses 
200
OK


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/highAvailabilityCluster/changeCluster
Request samples 
application/json
{
  • "clusterEndpoint": "172.24.29.165",
  • "clusterDnsName": "ha-cluster-01.tech.local",
  • "primaryNodeExternalEndpoint": "172.24.29.163:9419",
  • "secondaryNodeExternalEndpoint": "172.24.29.164:9419"
}
Response samples 
application/json
{
  • "sessionType": "HaClusterEdit",
  • "state": "Working",
  • "id": "4a3dba50-fb5d-427e-af56-3534b866daaa",
  • "name": "HaClusterEditing",
  • "jobId": "4a3dba50-fb5d-427e-af56-3534b866daaa",
  • "creationTime": "2026-07-03T12:00:54+02:00",
  • "progressPercent": 0,
  • "result": {
    },
  • "usn": 2273,
  • "initiatedBy": "veeamadmin",
  • "originalSessionId": "4a3dba50-fb5d-427e-af56-3534b866daaa"
}
Start High Availability Cluster Switchover
The HTTP POST request to the /api/v1/highAvailabilityCluster/switchover endpoint starts a switchover operation that swaps primary and secondary node roles in the High Availability cluster.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
optional
Optional switchover parameters. If omitted, default behavior applies (rejects if replication lag exists).


ignoreLag
boolean
 Default:  false
If true, proceeds with switchover despite replication lag, accepting potential data loss.


 
Responses 
200
Switchover operation has been started. To check the progress, track the session state.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/highAvailabilityCluster/switchover
Request samples 
application/json
{
  • "ignoreLag": false
}
Response samples 
application/json
{
  • "sessionType": "HaSwitchover",
  • "state": "Working",
  • "id": "6c1d3e50-7f28-4a91-b2c4-5d8e0f3a7b16",
  • "name": "HaSwitchover",
  • "jobId": "6c1d3e50-7f28-4a91-b2c4-5d8e0f3a7b16",
  • "creationTime": "2026-07-03T12:05:20+02:00",
  • "progressPercent": 0,
  • "result": {
    },
  • "usn": 2287,
  • "initiatedBy": "veeamadmin",
  • "originalSessionId": "6c1d3e50-7f28-4a91-b2c4-5d8e0f3a7b16"
}
Start High Availability Cluster Failover
The HTTP POST request to the /api/v1/highAvailabilityCluster/failover endpoint starts a failover operation that promotes a secondary node to the primary role in the High Availability cluster.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
202
Failover operation has been started.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/highAvailabilityCluster/failover
Request samples 
Response samples 
application/json
{
  • "message": "string"
}