Hypervisors Api Preflight Standalone Host

Hypervisors Api Preflight Standalone Host
Check a standalone ESXi host before adding it

Connects to the host and reports its reachability, certificate and credentials without storing anything. Requires the ADMIN role.

Request
URI
POST
https://{api_host}/api/v1/hypervisors/standalone/preflight
COPY
Request Body

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.

CreateStandaloneHypervisorRequest of type(s) application/json
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
}
string
hostname
Required  

Hostname or IP address

integer As int32 As int32
port
Optional
Constraints: minimum: 1 maximum: 65535

TCP port of the ESXi host, from 1 to 65535; 443 when omitted or not above 0

string
username
Required  

Account used to authenticate to the ESXi host; required and not blank

string As password As password
password
Required  

Password of the ESXi account; required and not blank; a write-only credential that is never returned by the API

string
expectedFingerprint
Optional

SHA-256 fingerprint of the certificate the administrator confirmed

boolean
acceptCertificate
Optional

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)

boolean
transferOwnership
Optional

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

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The preflight result for the host

Returns PreflightStandaloneResponse of type(s) application/json
{
    "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"
}
string
hostname
Required  

Hostname or IP address that was probed, trimmed

integer As int32 As int32
port
Required  

Port that was probed; 443 when the request gave none

boolean
reachable
Required  

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

string
certificateFingerprintSha256
Optional

SHA-256 fingerprint of the certificate the host presented; null when the host is unreachable

string
certificateSubject
Optional

Subject of the certificate the host presented; null when the host is unreachable

string
certificateIssuer
Optional

Issuer of the certificate the host presented; null when the host is unreachable

string
hardwareUuid
Optional

Hardware UUID candidate resolved from the authentication exchange or, failing that, the service content probe; null when the host is unreachable

string
esxiVersion
Optional

ESXi version from the service content probe; null when the host is unreachable or reported none

string
esxiBuild
Optional

ESXi build from the service content probe; null when the host is unreachable or reported none

boolean
credentialsValid
Required  

Whether the host accepted the supplied credentials in the token exchange; false when the host is unreachable

boolean
certificateTrusted
Required  

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

string
errorMessage
Optional

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

400 Bad Request: VALIDATION_FAILED, MALFORMED_REQUEST, INVALID_HOST or DUPLICATE_HOST

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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).

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    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