Hypervisors Api Enroll Hypervisor
Starts agent enrollment for one hypervisor. The request body is optional. Requires the ADMIN role.
Hypervisor key
103
Optional enrollment settings: consoleUrl, securityGroupId or securityGroupName, and heartbeatIntervalSeconds. The body can be left out, and a field that is left out is resolved by the server.
{
"consoleUrl": "https://console.example.com",
"securityGroupName": "Production Servers",
"heartbeatIntervalSeconds": 30
}
Base URL the Agent uses to reach the Console, with trailing slashes removed; when omitted the configured Console URL (setting vtp.console.url) is used and the enrollment fails if none is configured
securityGroupId
Name of the Group a newly created Agent for this host joins, matched ignoring case; the Default Group is used when omitted or not found; not applied when the host's existing Agent identity is reused
Heartbeat interval in seconds sent to the Agent during enrollment; a value above 0 is used as given, otherwise the interval of the Agent's Group, otherwise 30
200 OK successful response envelope. The enrollment response for the host
{
"hypervisorPk": 103,
"agentId": "3",
"status": "ENROLLING",
"message": "Enrollment commands accepted by agent daemon; awaiting first outbound heartbeat",
"timestamp": "2026-01-15T09:30:00Z"
}
Identifier of the hypervisor this result belongs to
Identifier of the Agent bound to the host, as a decimal string (a 64-bit value, sent as a string because browsers cannot hold it exactly as a number); null in the result of a batch entry whose enrollment raised an error
Enrollment status of the host after the call, using the values of HypervisorHostEnrollmentStatus: ENROLLING when the Agent accepted the enrollment or one is already in progress, ENROLLED when the host was already enrolled, FAILED for a batch entry whose enrollment raised an error
Text describing the outcome; for a batch entry that raised an error it starts with Enrollment failed:
Time the result was produced by the server
400 Bad Request: INVALID_ARGUMENT when the id path variable is not a number; MALFORMED_REQUEST when a body is sent and cannot be read
{
"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.
404 Not Found: HYPERVISOR_NOT_FOUND
"ApiErrorResponse Object"
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.
409 Conflict: RECOVERY_REQUIRED, VIB_NOT_INSTALLED, VIB_VERSION_INCOMPATIBLE, VIB_VERIFICATION_FAILED, AGENT_PENDING_CONFLICT or AGENT_ACTIVE_CONFLICT
"ApiErrorResponse Object"
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 '{}' https://{api_host}/api/v1/hypervisors/{id}/enroll