Hypervisors Api Preflight Standalone Host
Connects to the host and reports its reachability, certificate and credentials without storing anything. Requires the ADMIN role.
The standalone host to check before it is added: hostname, optional port, username and password, and the certificate thumbprint the operator confirmed. hostname, username and password are required.
Show optional properties
{
"hostname": "string",
"username": "string",
"password": "string"
}
{
"hostname": "esx01.example.com",
"port": 443,
"username": "esxuser.example",
"password": "<redacted>",
"expectedFingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"acceptCertificate": false,
"transferOwnership": false
}
Hostname or IP address
TCP port of the ESXi host, from 1 to 65535; 443 when omitted or not above 0
Account used to authenticate to the ESXi host; required and not blank
Password of the ESXi account; required and not blank; a write-only credential that is never returned by the API
SHA-256 fingerprint of the certificate the administrator confirmed
Acknowledges the certificate review. It does not authorize a certificate by itself: a certificate that is self-signed or not trusted by the system CA is accepted only together with expectedFingerprint, and without it is rejected with CERTIFICATE_FINGERPRINT_REQUIRED (CERTIFICATE_CONFIRMATION_REQUIRED when this flag is also absent)
When true, a host that is already managed through vCenter may be taken over as a standalone host (the same record is updated in place), but only when its vCenter record is STALE, is the single candidate, is proven by the live host's hardware UUID and matches the registration address; without it such a host is rejected with OWNERSHIP_TRANSFER_REQUIRED, and a host that cannot be taken over is rejected with OWNERSHIP_CONFLICT
200 OK successful response envelope. The preflight result for the host
{
"hostname": "esx01.example.com",
"port": 443,
"reachable": true,
"certificateFingerprintSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"certificateSubject": "CN=esx01.example.com,O=Example Org,C=US",
"certificateIssuer": "CN=esx01.example.com,O=Example Org,C=US",
"hardwareUuid": "00000000-0000-4000-8000-000000000011",
"esxiVersion": "8.0.2",
"esxiBuild": "20000000",
"credentialsValid": false,
"certificateTrusted": true,
"errorMessage": "Invalid username or password"
}
Hostname or IP address that was probed, trimmed
Port that was probed; 443 when the request gave none
Whether a TLS connection to the host succeeded; when false the certificate, hardware, version and build fields are null, credentialsValid and certificateTrusted are false and errorMessage explains why
SHA-256 fingerprint of the certificate the host presented; null when the host is unreachable
Subject of the certificate the host presented; null when the host is unreachable
Issuer of the certificate the host presented; null when the host is unreachable
Hardware UUID candidate resolved from the authentication exchange or, failing that, the service content probe; null when the host is unreachable
ESXi version from the service content probe; null when the host is unreachable or reported none
ESXi build from the service content probe; null when the host is unreachable or reported none
Whether the host accepted the supplied credentials in the token exchange; false when the host is unreachable
Whether the presented certificate matches expectedFingerprint when one was given, else the fingerprint already pinned for the host, else is trusted by the system CA; false when the host is unreachable
Host unreachable: followed by the reason when the host cannot be reached, otherwise the error text of the credentials check; null when there is none
400 Bad Request: VALIDATION_FAILED, MALFORMED_REQUEST, INVALID_HOST or DUPLICATE_HOST
{
"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.
409 Conflict: OWNERSHIP_CONFLICT or OWNERSHIP_TRANSFER_REQUIRED. OWNERSHIP_TRANSFER_REQUIRED means a detached vCenter record is the only candidate and every ownership proof holds, but transferOwnership was not sent; nothing is written. OWNERSHIP_CONFLICT means the host cannot be taken over and the message says why. The body carries errorCode (ApiErrorResponse).
"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 '{"hostname":"string","username":"string","password":"string"}' https://{api_host}/api/v1/hypervisors/standalone/preflight