VCenter Connections Delete

VCenter Connections Delete
Remove a registered vCenter connection

Stops the active discovery worker and removes the registered vCenter connection while preserving discovered inventory history. Agent unenrollment runs on the enrollment workers and the request waits at most vtp.vcenter.removal.max-request-wait-seconds (default 25) for it. 200 means every host has an outcome and the answer is final (REMOVED, or ATTENTION_REQUIRED when a host failed); 202 means hosts are still being offboarded, the connection stays REMOVING and is removed by the background work when the last host has an outcome. Repeating the call reports the existing durable operation and submits no host again. The force parameter no longer exists; any force value answers 400 FORCE_NOT_SUPPORTED. Requires the ADMIN role.

Request
URI
DELETE
https://{api_host}/api/v1/vcenter-connections/{id}
COPY
Path Parameters
string
id
Required  

Identifier of the vCenter connection: its numeric primary key, with or without the db- prefix (1 and db-1 name the same connection; responses carry the prefixed form). A value that is not a number answers 400 INVALID_CONNECTION_ID; an unknown connection answers 404.

id example
1

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK. Every host has an outcome and the answer is final. The connection is REMOVED (and no longer listed) after its discovery worker stops, its enrollment campaigns are cancelled, automatic enrollment is turned off and the agents of its hosts are offboarded; its discovered hosts are marked stale and the inventory history is kept. ATTENTION_REQUIRED means a host failed and the connection was kept so the operator can retry or force the removal

Returns VCenterConnectionSummary of type(s) application/json
{
    "id": "1",
    "displayName": "Primary vCenter",
    "host": "vcenter.example.com",
    "port": 443,
    "username": "svcvtp.example",
    "enabled": false,
    "vcenterInstanceUuid": "00000000-0000-4000-8000-000000000021",
    "trustProvenance": "USER_APPROVED",
    "certSha256": "01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF",
    "certSubject": "CN=vcenter.example.com,O=Example Org",
    "certNotAfter": "2026-03-31T00:00:00Z",
    "lastConnectionStatus": "REMOVED",
    "lastConnectionSecurityCode": "NONE",
    "createdAt": "2026-01-15T09:20:00Z",
    "discoveredHostCount": null,
    "discoveredHostCountStatus": null,
    "lastVerifiedSyncAt": null,
    "inventoryHoldReason": null,
    "inventoryHoldObservedHosts": null,
    "inventoryHoldCurrentHosts": null,
    "inventoryHoldId": null,
    "inventoryHoldExcludedProductHosts": null,
    "removalProgress": null
}
string
id
Required  

Unique database identifier for the connection

string
displayName
Required  

Operator-chosen name of the connection, trimmed of surrounding spaces when the connection is added; unique ignoring case

string
host
Required  

Host address

integer As int32 As int32
port
Required  

HTTPS port

string
username
Required  

Account the Console signs in to vCenter with, trimmed of surrounding spaces when the connection is added; the password is never returned

boolean
enabled
Required  

Whether discovery is currently enabled for this connection

string
vcenterInstanceUuid
Required  

Authoritative vCenter instance UUID

string
trustProvenance
Required  

Provenance of trust for the active vCenter certificate

  • CA_SAN_VERIFIED: The certificate passed strict CA and subject alternative name validation; also the value when none is given
  • USER_APPROVED: An administrator approved the certificate through a trust challenge, and the connection is pinned to it
Enumeration: CA_SAN_VERIFIED, USER_APPROVED
string
certSha256
Optional

SHA-256 fingerprint of the trusted leaf certificate

string
certSubject
Optional

Subject of the trusted leaf certificate

string As date-time As date-time
certNotAfter
Optional

Expiration timestamp of the trusted leaf certificate

string
lastConnectionStatus
Required  

Operational lifecycle state of a vCenter discovery connection. The server code also declares WAITING_FOR_AGENTS (the code found no place that sets it); it is not in the enum list

  • DISCONNECTED: Not connected: the state after STOPPING, and the state reported when none is stored
  • CONNECTING: The initial state of a newly added connection, and the state of each connect attempt
  • BASELINING: The connection is made and the security code is cleared; the inventory baseline is being loaded
  • WATCHING: The baseline is loaded and the worker follows inventory changes
  • DEGRADED_RETRYING: A transient transport failure occurred (security code CONNECTIVITY_FAILURE); the worker retries
  • REBUILDING: The session or its change lineage was invalidated; the worker reconnects through CONNECTING and BASELINING
  • STOPPING: Shutdown is in progress; DISCONNECTED follows
  • OPERATOR_ACTION_REQUIRED: The worker stopped retrying until an operator acts; the security code names the reason (trust required, pinned certificate expired, identity mismatch, authentication failure or insufficient privilege)
  • REMOVING: Removal was requested; discovery is fenced and the Agents of the connection's hosts are being offboarded, so the connection is not removed yet
  • ATTENTION_REQUIRED: A removal pass finished with at least one host that could not be offboarded; the connection is kept so the operator can retry or force the removal
  • REMOVED: Every host has an outcome and the connection row was deleted; returned by the removal call only
Enumeration: DISCONNECTED, CONNECTING, BASELINING, WATCHING, DEGRADED_RETRYING, REBUILDING, STOPPING, OPERATOR_ACTION_REQUIRED, REMOVING, ATTENTION_REQUIRED, REMOVED
string
lastConnectionSecurityCode
Optional

Security or error reason code for an operator-action or degraded vCenter connection

  • NONE: No security or error condition; the value stored when a connection is added and whenever the worker reaches CONNECTING or BASELINING cleanly
  • TLS_TRUST_REQUIRED: Certificate verification failed on connect, or the pinned certificate is not yet valid (set with OPERATOR_ACTION_REQUIRED)
  • VCENTER_IDENTITY_MISMATCH: The live vCenter instance UUID differs from the one recorded for the connection (set with OPERATOR_ACTION_REQUIRED)
  • PINNED_CERTIFICATE_EXPIRED: The pinned certificate has expired and the expired-pin policy does not allow continuing (set with OPERATOR_ACTION_REQUIRED)
  • AUTHENTICATION_FAILURE: The vCenter rejected the stored credentials (set with OPERATOR_ACTION_REQUIRED)
  • INSUFFICIENT_PRIVILEGE: The account lacks the privilege to enumerate the inventory (set with OPERATOR_ACTION_REQUIRED)
  • CONNECTIVITY_FAILURE: The vCenter could not be reached or a transient transport failure occurred (set with DEGRADED_RETRYING)
Enumeration: NONE, TLS_TRUST_REQUIRED, VCENTER_IDENTITY_MISMATCH, PINNED_CERTIFICATE_EXPIRED, AUTHENTICATION_FAILURE, INSUFFICIENT_PRIVILEGE, CONNECTIVITY_FAILURE
string As date-time As date-time
createdAt
Required  

Creation timestamp

integer As int64 As int64
discoveredHostCount
Optional

Number of ACTIVE vCenter-managed hypervisor rows stored for this connection, the same rows Hypervisors, Discover lists by default; STALE and standalone rows are excluded. Read from the stored inventory, never from vCenter. Present on the list response only

string
discoveredHostCountStatus
Optional

Present on the list response only; null elsewhere

string As date-time As date-time
lastVerifiedSyncAt
Optional

Time of the last successful baseline or WaitForUpdatesEx reply of the running discovery worker, null until the first one after a Console start. Not stored. Present on the list response only

string
inventoryHoldReason
Optional

Why removal of hosts missing from a complete vCenter snapshot is held: EMPTY_SNAPSHOT (no hosts although some are known) or MASS_REDUCTION (at least the configured number of hosts, and more than the configured percentage, would leave); null when no removal is held. Present on the list response only

Enumeration: EMPTY_SNAPSHOT, MASS_REDUCTION
integer As int32 As int32
inventoryHoldObservedHosts
Optional

Hosts the held snapshot listed; null without a hold. Present on the list response only

integer As int32 As int32
inventoryHoldCurrentHosts
Optional

Hosts currently known for the connection when the removal was held; null without a hold. Present on the list response only

string
inventoryHoldId
Optional

Identifier of the current hold, new for every hold; the confirmation must echo it so a confirmation made for one hold cannot apply to a later one. Null without a hold. Present on the list response only

integer As int32 As int32
inventoryHoldExcludedProductHosts
Optional

How many of the hosts whose removal is held are identified as unsupported mobility agent hosts, already hidden from Discover pending removal; 0 or null without a hold. Present on the list response only

object
removalProgress
Optional

Progress of Agent unenrollment while the connection is REMOVING, and the last pass's counts while it is ATTENTION_REQUIRED after a failed removal; null otherwise, and after a Console restart


202

202 Accepted. Agent unenrollment is still running on the enrollment workers; the connection is REMOVING, it is not removed yet, and removalProgress says how many hosts have finished and failed. The removal completes in the background; poll GET /api/v1/vcenter-connections to follow it

Returns VCenterConnectionSummary of type(s) application/json
{
    "id": "1",
    "displayName": "Primary vCenter",
    "host": "vcenter.example.com",
    "port": 443,
    "username": "svcvtp.example",
    "enabled": false,
    "vcenterInstanceUuid": "00000000-0000-4000-8000-000000000021",
    "trustProvenance": "USER_APPROVED",
    "certSha256": "01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF",
    "certSubject": "CN=vcenter.example.com,O=Example Org",
    "certNotAfter": "2026-03-31T00:00:00Z",
    "lastConnectionStatus": "REMOVING",
    "lastConnectionSecurityCode": "NONE",
    "createdAt": "2026-01-15T09:20:00Z",
    "discoveredHostCount": null,
    "discoveredHostCountStatus": null,
    "lastVerifiedSyncAt": null,
    "inventoryHoldReason": null,
    "inventoryHoldObservedHosts": null,
    "inventoryHoldCurrentHosts": null,
    "inventoryHoldId": null,
    "inventoryHoldExcludedProductHosts": null,
    "removalProgress": {
        "operationId": 7,
        "operationState": "RUNNING",
        "attentionReason": null,
        "hostsTotal": 120,
        "hostsFinished": 40,
        "hostsFailed": 1,
        "hostsOutstanding": 80,
        "remoteConfirmed": 37,
        "noRemoteIdentity": 2,
        "forcedUnconfirmed": 0,
        "recoveryRequired": 1
    }
}
string
id
Required  

Unique database identifier for the connection

string
displayName
Required  

Operator-chosen name of the connection, trimmed of surrounding spaces when the connection is added; unique ignoring case

string
host
Required  

Host address

integer As int32 As int32
port
Required  

HTTPS port

string
username
Required  

Account the Console signs in to vCenter with, trimmed of surrounding spaces when the connection is added; the password is never returned

boolean
enabled
Required  

Whether discovery is currently enabled for this connection

string
vcenterInstanceUuid
Required  

Authoritative vCenter instance UUID

string
trustProvenance
Required  

Provenance of trust for the active vCenter certificate

  • CA_SAN_VERIFIED: The certificate passed strict CA and subject alternative name validation; also the value when none is given
  • USER_APPROVED: An administrator approved the certificate through a trust challenge, and the connection is pinned to it
Enumeration: CA_SAN_VERIFIED, USER_APPROVED
string
certSha256
Optional

SHA-256 fingerprint of the trusted leaf certificate

string
certSubject
Optional

Subject of the trusted leaf certificate

string As date-time As date-time
certNotAfter
Optional

Expiration timestamp of the trusted leaf certificate

string
lastConnectionStatus
Required  

Operational lifecycle state of a vCenter discovery connection. The server code also declares WAITING_FOR_AGENTS (the code found no place that sets it); it is not in the enum list

  • DISCONNECTED: Not connected: the state after STOPPING, and the state reported when none is stored
  • CONNECTING: The initial state of a newly added connection, and the state of each connect attempt
  • BASELINING: The connection is made and the security code is cleared; the inventory baseline is being loaded
  • WATCHING: The baseline is loaded and the worker follows inventory changes
  • DEGRADED_RETRYING: A transient transport failure occurred (security code CONNECTIVITY_FAILURE); the worker retries
  • REBUILDING: The session or its change lineage was invalidated; the worker reconnects through CONNECTING and BASELINING
  • STOPPING: Shutdown is in progress; DISCONNECTED follows
  • OPERATOR_ACTION_REQUIRED: The worker stopped retrying until an operator acts; the security code names the reason (trust required, pinned certificate expired, identity mismatch, authentication failure or insufficient privilege)
  • REMOVING: Removal was requested; discovery is fenced and the Agents of the connection's hosts are being offboarded, so the connection is not removed yet
  • ATTENTION_REQUIRED: A removal pass finished with at least one host that could not be offboarded; the connection is kept so the operator can retry or force the removal
  • REMOVED: Every host has an outcome and the connection row was deleted; returned by the removal call only
Enumeration: DISCONNECTED, CONNECTING, BASELINING, WATCHING, DEGRADED_RETRYING, REBUILDING, STOPPING, OPERATOR_ACTION_REQUIRED, REMOVING, ATTENTION_REQUIRED, REMOVED
string
lastConnectionSecurityCode
Optional

Security or error reason code for an operator-action or degraded vCenter connection

  • NONE: No security or error condition; the value stored when a connection is added and whenever the worker reaches CONNECTING or BASELINING cleanly
  • TLS_TRUST_REQUIRED: Certificate verification failed on connect, or the pinned certificate is not yet valid (set with OPERATOR_ACTION_REQUIRED)
  • VCENTER_IDENTITY_MISMATCH: The live vCenter instance UUID differs from the one recorded for the connection (set with OPERATOR_ACTION_REQUIRED)
  • PINNED_CERTIFICATE_EXPIRED: The pinned certificate has expired and the expired-pin policy does not allow continuing (set with OPERATOR_ACTION_REQUIRED)
  • AUTHENTICATION_FAILURE: The vCenter rejected the stored credentials (set with OPERATOR_ACTION_REQUIRED)
  • INSUFFICIENT_PRIVILEGE: The account lacks the privilege to enumerate the inventory (set with OPERATOR_ACTION_REQUIRED)
  • CONNECTIVITY_FAILURE: The vCenter could not be reached or a transient transport failure occurred (set with DEGRADED_RETRYING)
Enumeration: NONE, TLS_TRUST_REQUIRED, VCENTER_IDENTITY_MISMATCH, PINNED_CERTIFICATE_EXPIRED, AUTHENTICATION_FAILURE, INSUFFICIENT_PRIVILEGE, CONNECTIVITY_FAILURE
string As date-time As date-time
createdAt
Required  

Creation timestamp

integer As int64 As int64
discoveredHostCount
Optional

Number of ACTIVE vCenter-managed hypervisor rows stored for this connection, the same rows Hypervisors, Discover lists by default; STALE and standalone rows are excluded. Read from the stored inventory, never from vCenter. Present on the list response only

string
discoveredHostCountStatus
Optional

Present on the list response only; null elsewhere

string As date-time As date-time
lastVerifiedSyncAt
Optional

Time of the last successful baseline or WaitForUpdatesEx reply of the running discovery worker, null until the first one after a Console start. Not stored. Present on the list response only

string
inventoryHoldReason
Optional

Why removal of hosts missing from a complete vCenter snapshot is held: EMPTY_SNAPSHOT (no hosts although some are known) or MASS_REDUCTION (at least the configured number of hosts, and more than the configured percentage, would leave); null when no removal is held. Present on the list response only

Enumeration: EMPTY_SNAPSHOT, MASS_REDUCTION
integer As int32 As int32
inventoryHoldObservedHosts
Optional

Hosts the held snapshot listed; null without a hold. Present on the list response only

integer As int32 As int32
inventoryHoldCurrentHosts
Optional

Hosts currently known for the connection when the removal was held; null without a hold. Present on the list response only

string
inventoryHoldId
Optional

Identifier of the current hold, new for every hold; the confirmation must echo it so a confirmation made for one hold cannot apply to a later one. Null without a hold. Present on the list response only

integer As int32 As int32
inventoryHoldExcludedProductHosts
Optional

How many of the hosts whose removal is held are identified as unsupported mobility agent hosts, already hidden from Discover pending removal; 0 or null without a hold. Present on the list response only

object
removalProgress
Optional

Progress of Agent unenrollment while the connection is REMOVING, and the last pass's counts while it is ATTENTION_REQUIRED after a failed removal; null otherwise, and after a Console restart


400

400 Bad Request: INVALID_CONNECTION_ID when the id is not a number, with or without a db- prefix; FORCE_NOT_SUPPORTED when a force parameter is present

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 when the signed-in role is not allowed to call this operation; 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 ForbiddenWrite 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.


404

404 Not Found: CONNECTION_NOT_FOUND when no connection has the id

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.


Code Samples
COPY
                    curl -X DELETE -H 'Authorization: <value>' https://{api_host}/api/v1/vcenter-connections/{id}