Hypervisors Api Enroll Hypervisors Batch
Starts agent enrollment for each listed hypervisor and reports a result per host. Requires the ADMIN role.
The ids of the hypervisors to enroll, with the optional securityGroupName, consoleUrl and heartbeatIntervalSeconds that apply to every listed host.
Show optional properties
{
"hypervisorIds": [
{}
]
}
{
"hypervisorIds": [
104,
105
],
"securityGroupName": "Production Servers",
"consoleUrl": "https://console.example.com",
"heartbeatIntervalSeconds": 30
}
Identifiers of the hypervisors to enroll; an empty or missing list yields an empty result, and a list longer than the batch limit (setting vtp.enrollment.batch-limit, 10 by default) is rejected
Name of the Group a newly created Agent joins, applied to every host with the same matching and fallback as the single-host enrollment request
Base URL the Agents use to reach the Console, applied to every host with the same defaulting as the single-host enrollment request
Heartbeat interval in seconds sent to every Agent during enrollment, with the same defaulting as the single-host enrollment request
200 OK successful response envelope. The enrollment result for each listed host
{
"totalRequested": 2,
"succeededCount": 2,
"failedCount": 0,
"results": [
{
"hypervisorPk": 104,
"agentId": "4",
"status": "ENROLLING",
"message": "Enrollment commands accepted by agent daemon; awaiting first outbound heartbeat",
"timestamp": "2026-01-15T09:30:00Z"
},
{
"hypervisorPk": 105,
"agentId": "5",
"status": "ENROLLING",
"message": "Enrollment commands accepted by agent daemon; awaiting first outbound heartbeat",
"timestamp": "2026-01-15T09:30:00Z"
}
]
}
Number of results returned, one per hypervisor identifier in the request; 0 for an empty request
Number of results whose status is ENROLLED or ENROLLING
Number of results with any other status
One result per requested hypervisor identifier, in request order
400 Bad Request: MALFORMED_REQUEST when the body is missing or cannot be read, for example when hypervisorIds holds a value that is not a number
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"hypervisorIds":["integer"]}' https://{api_host}/api/v1/hypervisors/enroll-batch