Hypervisors Api Start Agent Software Check
Starts a check of 1 to 10 selected hypervisors (the limit is vtp.discovery.software-inventory.manual-max-hosts, at most 25) and answers at once. Hosts are checked one at a time. The server derives each host's source: its vCenter connection, or the host itself when standalone. At most 2 checks run at once and one per source; there is no queue. Requires the ADMIN role.
The hypervisor ids to check
Show optional properties
{
"hypervisorIds": [
{}
]
}
{
"hypervisorIds": [
101,
102
]
}
Hypervisor ids, 1 to the configured limit (default 10)
200 OK: the identical selection is already running; its job is returned and nothing new starts.
{
"jobId": "vibjob-00000000-0000-4000-8000-000000000011",
"status": "RUNNING",
"total": 2,
"completed": 1,
"installed": 1,
"notInstalled": 0,
"heldInstalled": 0,
"shared": 0,
"inconclusive": 0,
"hosts": [
{
"hypervisorId": 101,
"hostname": "host-a.example.com",
"source": "vcenter:db-1",
"outcome": "INSTALLED",
"reason": null
},
{
"hypervisorId": 102,
"hostname": "host-b.example.com",
"source": "vcenter:db-1",
"outcome": "CHECKING",
"reason": null
}
],
"startedAt": "2026-01-16T10:00:00Z",
"completedAt": null
}
Identifier to poll with GET /api/v1/hypervisors/agent-software-checks/{jobId}
RUNNING while hosts remain. COMPLETED when this run confirmed or shared every host. COMPLETED_WITH_GAPS when any host was held or inconclusive. FAILED when the job stopped on an error.
Hosts in the job
Hosts the job has finished with so far
Hosts this run confirmed Installed
Hosts this run confirmed Not installed
Hosts whose check timed out while the earlier Installed status was kept
Hosts covered by another check, not verified by this run
Hosts this run could not confirm
One entry per host, in selection order
Time the job started
When the last host finished; null while running
202 Accepted: the check started. It continues after the response; poll GET /api/v1/hypervisors/agent-software-checks/{jobId} for the outcome.
{
"jobId": "vibjob-00000000-0000-4000-8000-000000000011",
"status": "RUNNING",
"total": 2,
"completed": 1,
"installed": 1,
"notInstalled": 0,
"heldInstalled": 0,
"shared": 0,
"inconclusive": 0,
"hosts": [
{
"hypervisorId": 101,
"hostname": "host-a.example.com",
"source": "vcenter:db-1",
"outcome": "INSTALLED",
"reason": null
},
{
"hypervisorId": 102,
"hostname": "host-b.example.com",
"source": "vcenter:db-1",
"outcome": "CHECKING",
"reason": null
}
],
"startedAt": "2026-01-16T10:00:00Z",
"completedAt": null
}
Identifier to poll with GET /api/v1/hypervisors/agent-software-checks/{jobId}
RUNNING while hosts remain. COMPLETED when this run confirmed or shared every host. COMPLETED_WITH_GAPS when any host was held or inconclusive. FAILED when the job stopped on an error.
Hosts in the job
Hosts the job has finished with so far
Hosts this run confirmed Installed
Hosts this run confirmed Not installed
Hosts whose check timed out while the earlier Installed status was kept
Hosts covered by another check, not verified by this run
Hosts this run could not confirm
One entry per host, in selection order
Time the job started
When the last host finished; null while running
400 Bad Request: VIB_CHECK_INVALID_SELECTION. No host, too many hosts, a duplicate, or a host that is unknown, not active or has no source.
{
"code": "VIB_CHECK_INVALID_SELECTION",
"message": "Select at most 10 hosts to check at a time.",
"runningJobId": null,
"busySources": []
}
Machine-readable reason
Text safe to show to the operator
For VIB_CHECK_SOURCE_BUSY, the running job that holds the source
For VIB_CHECK_SOURCE_BUSY, the sources held, as vcenter:
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.
409 Conflict: VIB_CHECK_SOURCE_BUSY. A different selection shares a source that a running check already covers.
{
"code": "VIB_CHECK_SOURCE_BUSY",
"message": "An Agent software check is already running for vcenter:db-1. Wait for it to finish, then check again.",
"runningJobId": "vibjob-00000000-0000-4000-8000-000000000011",
"busySources": [
"vcenter:db-1"
]
}
Machine-readable reason
Text safe to show to the operator
For VIB_CHECK_SOURCE_BUSY, the running job that holds the source
For VIB_CHECK_SOURCE_BUSY, the sources held, as vcenter:
429 Too Many Requests: VIB_CHECK_CAPACITY. Two checks are already running.
{
"code": "VIB_CHECK_CAPACITY",
"message": "The Console is already running 2 Agent software checks. Try again in a moment.",
"runningJobId": null,
"busySources": []
}
Machine-readable reason
Text safe to show to the operator
For VIB_CHECK_SOURCE_BUSY, the running job that holds the source
For VIB_CHECK_SOURCE_BUSY, the sources held, as vcenter:
Response Headers
Seconds to wait before trying again.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"hypervisorIds":["integer"]}' https://{api_host}/api/v1/hypervisors/agent-software-checks