Hypervisors Api Add Standalone Host

Hypervisors Api Add Standalone Host
Add a standalone ESXi host

Registers a standalone host, pinning the certificate the administrator confirmed. Requires the ADMIN role.

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

The standalone host to add: 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
201

201 Created successful response envelope. The created standalone host

Returns HypervisorSummaryDto of type(s) application/json
{
    "id": "101",
    "vcenterId": null,
    "hostname": "esx01.example.com",
    "parentLocator": null,
    "connectionState": "CONNECTED",
    "inMaintenanceMode": false,
    "esxiVersion": "8.0.2",
    "esxiBuild": "20000000",
    "inventoryState": "ACTIVE",
    "stale": false,
    "observedAt": "2026-01-15T09:30:00Z",
    "firstObservedAt": "2026-01-15T09:30:00Z",
    "agentCorrelationState": "NOT_CORRELATED",
    "vcenterConnectionId": null,
    "vcenterInstanceUuid": null,
    "hardwareUuid": "00000000-0000-4000-8000-000000000011",
    "vcenterDisplayName": "Standalone ESXi",
    "agentId": null,
    "enrollmentStatus": "NOT_ENROLLED",
    "enrolledAt": null,
    "enrollmentError": null,
    "agentVibStatus": "UNKNOWN",
    "agentVibIdentifier": null,
    "agentVibVersion": null,
    "agentVibDisplayName": null,
    "enrollmentStage": "NONE",
    "agentCommStatus": null,
    "lastHeartbeatAt": null,
    "clusterName": null,
    "managementType": "STANDALONE",
    "autoEnrollSuppressedAt": null,
    "authUsername": null,
    "hardwareIdentityConflict": false,
    "agentVibConfirmedAt": null,
    "agentVibLastAttemptAt": null,
    "agentVibLastAttemptResult": null,
    "recoveryRequired": false,
    "recoveryReason": null
}
string
id
Required  

Hypervisor key

string
vcenterId
Optional

Identifier of the vCenter connection that owns the host, the same value as vcenterConnectionId (kept as an alias for older clients); null once the host is registered as a standalone host

string
hostname
Optional

Hostname of the host as reported by vCenter, or the hostname or IP address given when a standalone host was registered

string
parentLocator
Optional

Locator of the host's parent inventory object as reported by vCenter, for example a cluster identifier such as domain-c76; null when none was reported

connectionState
Optional

Connection state of the host as reported by vCenter at the last observation; UNKNOWN until one is reported

boolean
inMaintenanceMode
Required  

Whether vCenter reported the host to be in maintenance mode at the last observation

string
esxiVersion
Optional

ESXi version of the host as last reported by vCenter or by the standalone host probe; null when none was reported

string
esxiBuild
Optional

ESXi build of the host as last reported by vCenter or by the standalone host probe; null when none was reported

inventoryState
Optional

Whether the latest inventory still reports the host: ACTIVE while it is reported, STALE after vCenter reported it leaving or its vCenter connection is no longer an active source; the row is kept in both cases

boolean
stale
Required  

Whether the host was last observed longer ago than the freshness threshold (setting vtp.discovery.freshness-threshold-minutes, 15 minutes by default); evaluated when the list is read and independent of inventoryState

string As date-time As date-time
observedAt
Optional

Time of the last discovery observation of the host

string As date-time As date-time
firstObservedAt
Optional

Time the host was first observed, set once when its row was created

string
agentCorrelationState
Required  

Whether the host is correlated with an agent.

  • NOT_CORRELATED: The host has no Agent identity, or its enrollment status is neither ENROLLED, ENROLLING nor FAILED
  • CORRELATED: The host has an Agent identity and its enrollment status is ENROLLED
  • PENDING: The host has an Agent identity and its enrollment status is ENROLLING
  • FAILED: The host has an Agent identity and its enrollment status is FAILED
Enumeration: NOT_CORRELATED, CORRELATED, PENDING, FAILED
string
vcenterConnectionId
Optional

Identifier of the vCenter connection that owns the host, the same value as vcenterId; null once the host is registered as a standalone host

string
vcenterInstanceUuid
Optional

Instance UUID of the vCenter server that reported the host; null for a standalone host or when vCenter did not report one

string
hardwareUuid
Optional

Hardware UUID of the host (vCenter summary.hardware.uuid), the candidate durable identity of the host; null when none was reported

string
vcenterDisplayName
Optional

Display name of the vCenter connection that owns the host; falls back to the vCenter identifier when the connection has no display name, and to Standalone ESXi for a standalone host without either

string As ^[0-9]+$
agentId
Optional

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 while no Agent identity is bound

string
enrollmentStatus
Required  

Agent enrollment status of a hypervisor host.

  • NOT_ENROLLED: No enrollment: the initial value of every host and the value after an enrollment reset or unenroll
  • ENROLLING: An Agent identity was allocated and the enrollment commands were sent; the host awaits the Agent's first heartbeat
  • ENROLLED: The Agent's first heartbeat after enrollment promoted the host from ENROLLING
  • FAILED: An enrollment step failed, the enrollment deadline passed while ENROLLING, or an unenroll could not be completed remotely (stage RECOVERY_REQUIRED)
  • UNENROLLED: No behaviour is documented for this value. No producing site in the current server code
Enumeration: NOT_ENROLLED, ENROLLING, ENROLLED, FAILED, UNENROLLED
string As date-time As date-time
enrolledAt
Optional

Time the host became ENROLLED; null unless enrollmentStatus is ENROLLED

string
enrollmentError
Optional

Error text of the last enrollment failure, including the timeout error reported when an ENROLLING host passed its enrollment deadline; null when there is none

string
agentVibStatus
Required  

State of the agent VIB on a hypervisor host.

  • INSTALLED: The vCenter software inventory lists the VTP Agent VIB component on the host
  • NOT_INSTALLED: The software inventory succeeded and the VIB is absent; the Agent of such a host is reported OFFLINE
  • UNKNOWN: The software inventory is unavailable, for example it was not queried or the host does not support it (the initial value); previously stored VIB facts are kept
  • QUERY_FAILED: The vCenter query returned an error, timed out or could not connect; previously stored VIB facts are kept
Enumeration: INSTALLED, NOT_INSTALLED, UNKNOWN, QUERY_FAILED
string
agentVibIdentifier
Optional

Identifier of the Agent VIB package taken from the vCenter software inventory; null when the inventory has not reported one

string
agentVibVersion
Optional

Version of the Agent VIB package taken from the vCenter software inventory; null when the inventory has not reported one

string
agentVibDisplayName
Optional

Display name of the Agent VIB package taken from the vCenter software inventory; null when the inventory has not reported one

string
enrollmentStage
Required  

Stage of the agent enrollment of a hypervisor host.

  • NONE: No enrollment step has run; the initial value and the value after an enrollment reset
  • AUTHORIZING: The Console is authenticating to the ESXi host to obtain a bearer token
  • CSR_REQUESTED: The Console asked the host's Agent to start enrollment and awaits its certificate signing request (CSR)
  • CSR_RECEIVED: The Agent returned a certificate signing request
  • CERT_SIGNED: The Console signed the Agent's certificate signing request
  • CERT_DELIVERED: The signed certificate was delivered to the Agent
  • AWAITING_HEARTBEAT: The certificate delivery was recorded and the host awaits the Agent's first heartbeat
  • ENROLLED: The Agent's first heartbeat promoted the host; set together with status ENROLLED
  • RECOVERY_REQUIRED: An unenroll could not be completed remotely and was not forced; the host keeps status FAILED and its Agent binding until the enrollment is reset with force=true
  • FAILED: An enrollment step failed or the enrollment deadline passed while ENROLLING
Enumeration: NONE, AUTHORIZING, CSR_REQUESTED, CSR_RECEIVED, CERT_SIGNED, CERT_DELIVERED, AWAITING_HEARTBEAT, ENROLLED, RECOVERY_REQUIRED, FAILED
string
agentCommStatus
Optional

Whether the Agent on this host is ONLINE or OFFLINE; OFFLINE is also reported when the Agent VIB is NOT_INSTALLED or when an ONLINE host has not sent a heartbeat within the freshness threshold (setting vtp.agent.heartbeat-freshness-threshold-seconds, 900 seconds by default: three missed heartbeats at the 300-second interval). The liveness sweep marks an Agent OFFLINE after three missed heartbeats of its group's interval and records AGENT_HEARTBEAT_MISSED and AGENT_OFFLINE in the audit log; null when the host has no Agent state

string As date-time As date-time
lastHeartbeatAt
Optional

Time of the last heartbeat received from the Agent; null when the host has no Agent state or no heartbeat was recorded

string
clusterName
Optional

Cluster name resolved from parentLocator by the cluster name resolver; null when no resolver is configured, the host has no parentLocator or no name is found

string
managementType
Required  

How the host is managed.

  • VCENTER_MANAGED: The host is discovered through a vCenter connection (the default)
  • STANDALONE: The host was registered directly with the Console as a standalone ESXi host; vCenter discovery does not write to it
Enumeration: VCENTER_MANAGED, STANDALONE
string As date-time As date-time
autoEnrollSuppressedAt
Optional

Time Auto-Enroll was suppressed for this host (an operator Unenroll, or an unconfirmed Force Remove); null when it is not suppressed. While set, the Console does not enroll the host automatically; an operator Enroll clears it. Marks written by earlier releases cannot be told apart from an operator's decision.

string
authUsername
Optional

User name of the account stored for direct (standalone) management of this host, shown so an operator can see which account the Console uses for the VIB check and the host connection; null for vCenter-managed hosts and for hosts with no stored account. Never a password.

boolean
hardwareIdentityConflict
Optional

True while discovery has seen a hardware identity different from the one this record's Agent or enrollment is bound to, in any enrollment state. Enrollment of the host cannot change until identity verification clears it (a verified unenrollment clears it). The observed identity itself is never returned.

string As date-time As date-time
agentVibConfirmedAt
Optional

Time a verification last confirmed agentVibStatus (INSTALLED or NOT_INSTALLED). A failed or inconclusive attempt never changes it, so a status with an old confirmation time is retained evidence, not a fresh check; null when the status was never confirmed (including rows that predate this field)

string As date-time As date-time
agentVibLastAttemptAt
Optional

Time of the most recent verification attempt, successful or not; null when none has run

string
agentVibLastAttemptResult
Optional

OK when the latest attempt confirmed the VIB state, otherwise a diagnostic reason code for why it confirmed nothing (never raw host or vCenter text); null when no attempt has run

boolean
recoveryRequired
Optional

True when the host record itself shows that Reset and Recover is needed: the recovery stage, or a forced reset that left the Agent's state unconfirmed. Independent of enrollmentStage. Ownership recorded only in the lifecycle history is not computed per list row; enrollment still refuses it with RECOVERY_REQUIRED

string
recoveryReason
Optional

Why recoveryRequired is true: RECOVERY_STAGE (a remote unenroll failed and the host is waiting for Recover) FORCED_RESET_UNCONFIRMED (a forced reset retired the Console's trust without remote confirmation, so an Agent may still hold the host), OWNERSHIP_UNCONFIRMED (lifecycle history ends in an unconfirmed release) or HISTORY_UNAVAILABLE (the history could not be read: unknown, not clear; Enroll must not be offered); null when recoveryRequired is false


400

400 Bad Request: VALIDATION_FAILED, MALFORMED_REQUEST, INVALID_REQUEST, AUTHENTICATION_FAILED, HOST_UNREACHABLE 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: CERTIFICATE_FINGERPRINT_MISMATCH, CERTIFICATE_CONFIRMATION_REQUIRED, CERTIFICATE_FINGERPRINT_REQUIRED, OWNERSHIP_CONFLICT or OWNERSHIP_TRANSFER_REQUIRED (see ApiErrorCode; the body carries errorCode)

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