HyperArmor API Documentation Operations Index

HyperArmor API Documentation Operations Index

All available HyperArmor API Documentation Operations

Agent Commands
GET
Agent Commands Api List

Latest state per command type for the agent. Requires the ADMIN role.

POST
Agent Commands Api Send

Queues a console command for delivery to the agent and answers 202 with its state. ActionUnenroll cannot be issued here; use the enrollment reset. Requires the ADMIN role.

Alert Rules
GET
Alert Rules Operations List

List all configured Alert Rules. Accessible to ADMIN, SECURITY_OPERATOR, and AUDITOR.

POST
Alert Rules Operations Create

Create a new Alert Rule and its delivery destination. Requires ADMIN or SECURITY_OPERATOR.

GET
Alert Rules Operations Get By Id

Retrieve an Alert Rule by ID. Accessible to ADMIN, SECURITY_OPERATOR, and AUDITOR.

PUT
Alert Rules Operations Update

Update an existing Alert Rule and its delivery destination. Bumps revision if qualification semantics change. Requires ADMIN or SECURITY_OPERATOR.

DELETE
Alert Rules Operations Delete

Delete an Alert Rule and its configured deliveries. Past alerts raised by this rule are preserved. Requires ADMIN or SECURITY_OPERATOR.

Alerts
GET
Alerts Operations List

Catch-up list for a client that reconnects its WebSocket. Returns the security and license-expiration alerts updated at or after since, in the requested states (every state when none is given), capped at limit (default 50, at most 200). It is not paginated. total and returned both equal the number of items in this response, so total is not a match count. Use /api/v1/alerts/search to investigate. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Also accepts a Bearer API token with Read-only or Full access.

GET
Alerts Operations Search

General investigation query over the security and license-expiration alerts, server-side filtered, sorted and paginated (page defaults to 0, pageSize to 20 with a maximum of 100, sorted by updatedAt DESC then alertId). Every state is returned when no state filter is given. An out-of-range page or pageSize, or an unknown state, groupMode, runtimeOutcome, sortBy or sortOrder, answers 400 (INVALID_PAGINATION, INVALID_FILTER or INVALID_SORT). For the WebSocket reconnect cursor use /api/v1/alerts. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Also accepts a Bearer API token with Read-only or Full access.

GET
Alerts Operations Export Csv

CSV of every security and license-expiration alert that matches the search filters (the same filters as /api/v1/alerts/search), not paginated and in ascending alertId order. The rows are read in one consistent snapshot taken when the export starts, so alerts created, changed or deleted during the export neither appear twice nor go missing. The response is text/csv with charset UTF-8, sent as an attachment named alerts-export-all-YYYY-MM-DD.csv (the current UTC date) with caching disabled. The first line is the header row, in this order, Alert ID, Title, Class, Severity, Hypervisor, Group, Matched Rule, Action, Group mode when received, Outcome, Events, State, Resolution, Created At, Updated At, Matched Rule Count, Matched Rules. The last two columns are new trailing columns; the earlier columns and their order are unchanged. Matched Rule Count is the number of distinct Rules that matched the alert, and Matched Rules is every Rule name joined with '; ' in the order the Rules first matched (the one Rule the alert names when none are stored). Alert ID, Severity, Events and Matched Rule Count are unquoted numbers (Severity is empty when absent); the other columns are enclosed in double quotes with embedded quotes doubled, and a value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote. Created At and Updated At are ISO-8601 UTC instants. An unknown state, groupMode or runtimeOutcome answers 400 INVALID_FILTER before any CSV is written. A failure after streaming has started aborts the connection, so the download fails instead of ending early. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Every attempt is audited (ALERTS_EXPORTED with the row count, or ALERTS_EXPORT_FAILED).

GET
Alerts Operations Count

Counts security and license-expiration alerts for the navigation badge. activeCount is newCount plus acknowledgedCount, and count is the number of alerts in the requested states (activeCount when no state is given). Every figure is counted over the whole matching set and never derived from a capped list page. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Also accepts a Bearer API token with Read-only or Full access.

GET
Alerts Operations Get By Id

Returns the full detail of one alert, including its state and its version. The version is the expectedVersion the acknowledge, resolve and false-positive requests must send back. 404 ALERT_NOT_FOUND when no alert has that id. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Also accepts a Bearer API token with Read-only or Full access.

POST
Alerts Operations Acknowledge

Moves an alert from NEW to ACKNOWLEDGED, records the acting user and time, and stores the optional analystNote (up to 2048 characters). The body must carry expectedVersion, the version read from the alert. 409 ALERT_INVALID_STATE_TRANSITION unless the alert is NEW, 409 ALERT_VERSION_CONFLICT when expectedVersion is missing or stale (refetch and retry), 404 ALERT_NOT_FOUND. Every success is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

POST
Alerts Operations Resolve

Moves an alert from NEW or ACKNOWLEDGED to RESOLVED with resolutionReason RESOLVED, records the acting user and time, and stores the optional analystNote (up to 2048 characters). The body must carry expectedVersion, the version read from the alert. 409 ALERT_INVALID_STATE_TRANSITION when the alert is already RESOLVED, 409 ALERT_VERSION_CONFLICT when expectedVersion is missing or stale (refetch and retry), 404 ALERT_NOT_FOUND. Every success is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

POST
Alerts Operations Mark False Positive

Same transition as resolve, from NEW or ACKNOWLEDGED to RESOLVED, but with resolutionReason FALSE_POSITIVE. Records the acting user and time and stores the optional analystNote (up to 2048 characters). The body must carry expectedVersion, the version read from the alert. 409 ALERT_INVALID_STATE_TRANSITION when the alert is already RESOLVED, 409 ALERT_VERSION_CONFLICT when expectedVersion is missing or stale (refetch and retry), 404 ALERT_NOT_FOUND. Every success is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

POST
Alerts Operations Bulk Acknowledge

Acknowledges each listed alert on its own, under the same rules as the single acknowledge (the alert must be NEW and its expectedVersion must match). The call is not atomic. It answers 200 with one outcome per item, either the updated alert or an errorCode and errorMessage, plus successCount and failureCount, and one item's failure never rolls back or hides the others. items must not be empty (400 otherwise). The analystNote, up to 2048 characters, applies to every item. A summary of the call is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

POST
Alerts Operations Bulk Resolve

Resolves each listed alert on its own, under the same rules as the single resolve (the alert must be NEW or ACKNOWLEDGED and its expectedVersion must match). The call is not atomic. It answers 200 with one outcome per item, either the updated alert or an errorCode and errorMessage, plus successCount and failureCount, and one item's failure never rolls back or hides the others. An alert that is already resolved is reported as ALERT_INVALID_STATE_TRANSITION in its own outcome. items must not be empty (400 otherwise). The analystNote, up to 2048 characters, applies to every item. A summary of the call is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

Api Tokens
GET
Api Tokens Overview Api List All Api Tokens

Returns one page of token metadata with the owner's username, newest first (createdAt, then internal id, both descending; the order cannot be changed). Includes revoked and expired tokens. It never returns the token, its digest or key material. Answers 404 API_TOKENS_DISABLED while the feature flag is off. Bearer tokens cannot call this route. To revoke a token found here, use DELETE /api/v1/users/{userId}/api-tokens/{tokenId} with the token's ownerUserId.

GET
Api Tokens Api List Api Tokens

Returns metadata only, newest first, at most 100 tokens, including revoked and expired ones. It never returns the token, its digest or key material. Answers 404 API_TOKENS_DISABLED while the feature flag is off. Bearer tokens cannot call this route.

POST
Api Tokens Api Create Api Token

The owner must be an active LOCAL user (the protected default administrator is eligible), and may hold at most 10 non-revoked, unexpired tokens. The response carries Cache-Control no-store and is the only time the token is returned. Audited as API_TOKEN_CREATE without the secret. Bearer tokens cannot call this route.

DELETE
Api Tokens Api Revoke Api Token

Idempotent: answers 204 also for a token that is already revoked. A token that does not belong to the path user is 404, so one user's tokens are not disclosed through another's path. Audited as API_TOKEN_REVOKE. Stays available while the licence is restricted because it only reduces risk. Bearer tokens cannot call this route.

Audit Logs
GET
Audit Logs Operations List

Search and list audit logs with multi-attribute filtering (Admin, Security Operator and Auditor).

GET
Audit Logs Operations Export Csv

CSV of every audit record that matches the Audit Logs list filters (the same filters as /api/v1/audit-logs), not paginated and newest first in descending audit ID order. The rows are read in one consistent snapshot taken when the export starts, so records written, changed or purged during the export neither appear twice nor go missing, and the export never contains its own audit record. The response is text/csv with charset UTF-8, sent as an attachment named audit-logs-export-YYYY-MM-DD.csv (the current UTC date) with caching disabled. The first line is the header row, in this order, Audit ID, Timestamp (UTC), Actor, Actor IP, Action, Target Type, Target ID, Target Name, Outcome, Details. Audit ID is an unquoted number; the other columns are enclosed in double quotes with embedded quotes doubled, and a value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote. Timestamp (UTC) is an ISO-8601 UTC instant and Details is the stored JSON object as text (empty when there are none). An unknown outcome, or from later than to, answers 400 INVALID_FILTER before any CSV is written. A failure after streaming has started aborts the connection, so the download fails instead of ending early. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role, the same roles that can read audit logs. Every attempt is audited (AUDIT_LOGS_EXPORTED with the row count, or AUDIT_LOGS_EXPORT_FAILED); the search text itself is not stored

GET
Audit Logs Operations Get By Id

Retrieve a single audit log event by ID (Admin, Security Operator and Auditor).

Authentication
POST
Auth Api Logout

Revokes the local session first and clears VTP_SESSION. For an SSO session that holds a stored ID token and a stored end_session_endpoint, the 200 body carries idpLogoutUrl (RP-initiated logout) and the client navigates to it once. Otherwise the body is an empty object and the logout is local-only. A failure of the IdP step never changes the status. The response is never cacheable because the URL carries the ID token. Accessible to every authenticated role, including while mustChangePassword is true.

GET
Sso Auth Api Get Auth Config

Returns what the login page needs before a session exists: ssoEnabled is true only when Enterprise SSO is configured and enabled, displayName is the configured SSO display name and is omitted when it is null (always when SSO is disabled), and apiDocsEnabled reports whether this API documentation page is served (vtp.api-docs.enabled, true by default). Public: no session required.

GET
Sso Auth Api Oidc Login

Answers 302 to the IdP authorization endpoint and sets the encrypted, callback-scoped request cookie (HttpOnly, Secure, SameSite=Lax, at most 10 minutes). When SSO is disabled or unavailable it answers 302 to the fixed internal login path /login, carrying only the error code SSO_DISABLED or SSO_UNAVAILABLE in the error query parameter (/login?error=). Public: no session required.

GET
Sso Auth Api Oidc Callback

On success answers 302 to a fixed internal path and sets VTP_SESSION and XSRF-TOKEN through the shared cookie helper; no return target is accepted and IdP tokens are never sent to the browser. On any failure answers 302 to the fixed internal login path /login, carrying only one fixed SsoErrorCode and no IdP-supplied text in the error query parameter (/login?error=). The request cookie is deleted on every outcome. Public: no session required.

POST
Auth Api Login

Authenticates a local account. On success sets the HttpOnly VTP_SESSION session cookie and the XSRF-TOKEN cookie. Every refusal (unknown user, wrong password, non-local account, empty fields) answers the same 401 INVALID_CREDENTIALS. Public: no session required. The 429 is produced by the gateway rate limit, not by this service.

GET
Auth Api Get Session

Returns the signed-in user. Also available while mustChangePassword is true, so the client can render the change-password screen. Accessible to every authenticated role.

POST
Auth Api Change Password

Changes the caller's own password (LOCAL accounts only) and clears mustChangePassword. A voluntary change keeps the current session and revokes every other active session of the user. A mandatory change (mustChangePassword was true) also revokes the current session and clears its cookie, and the body says reauthenticationRequired: true, so the client signs in again with the new password. While mustChangePassword is true this is one of the only operations allowed (with session and logout); all others answer 403 PASSWORD_CHANGE_REQUIRED. Five wrong current passwords within 15 minutes block further changes of that account until the window ends. Accessible to every authenticated role.

Dashboard
GET
Dashboard Operations Get Summary

Hypervisor and configuration-sync population is exactly what GET /api/v1/endpoints lists with no filters. connected + offline + unreported == managed; upToDate + pending + error + unreported == managed.

GET
Dashboard Operations Get Top Matched Rules

matchCount is the number of persisted Event rows attributed to the Rule in the window, not distinct alerts and not distinct hypervisors. Ordered by matchCount DESC, ruleId ASC.

Deployment
GET
Deployment Operations Get Summary

One snapshot over standalone hosts plus hosts whose stored vCenter connection reference belongs to a configured connection (the Discover membership rule, also when no connection exists). Never contacts vCenter or ESXi and never writes. Every totals field equals the sum over rows; agentVersions sums to totals.agentRollout.installed.

Endpoints
GET
Endpoints Operations List

Returns a paginated collection of endpoint summaries matching query criteria. Accessible to every authenticated role.

GET
Endpoints Operations Get By Id

Returns full operational, inventory, policy, and health detail for the endpoint. Accessible to every authenticated role.

POST
Endpoints Operations Unenroll

Resets the enrollment of the host that runs the endpoint. The path /api/v1/endpoints/{id}/reset-enrollment is an alias of this operation. Requires the ADMIN role.

POST
Endpoints Operations Move To Group

Moves the listed endpoints to the target Group and returns them as updated. Requires the ADMIN or SECURITY_OPERATOR role.

Enrollment Campaigns
POST
Enrollment Campaigns Api Create Campaign

Creates a campaign for the chosen scope; a scope that resolves to no hosts completes at once. Requires the ADMIN role.

GET
Enrollment Campaigns Api Get Settings

Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

PUT
Enrollment Campaigns Api Update Settings

A numeric field of zero or less is left unchanged; a null automaticEnrollmentPaused leaves the pause untouched. A globalWorkerConcurrency above its ceiling (default 32, property vtp.campaign.global-worker-concurrency-ceiling) or a maxConcurrentPerVcenter above its ceiling (default 20, property vtp.campaign.max-concurrent-per-vcenter-ceiling) answers 400 CONCURRENCY_OUT_OF_RANGE and changes nothing. A change to either concurrency value is recorded in the audit log as ENROLLMENT_CONCURRENCY_CHANGED. Requires the ADMIN role.

GET
Enrollment Campaigns Api Get Enrollment Metrics

Gauges of the resources enrollment shares (campaign workers, simultaneous vCenter token exchanges and how many were throttled) and one row per vCenter: queued, claimed and active counts, jobs completed, failed, cancelled and retried in the window, throughput per hour, and queue wait and slot occupancy percentiles. Queue wait is creation to start; slot occupancy is start to completion and is dominated by the wait for the Agent's first heartbeat. The number of rows is the number of vCenters, so the response does not grow with the number of hosts. No host name, credential or token appears. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Enrollment Campaigns Api Get Enrollment Performance

Per vCenter: the slots in effect now, whether they are the default or a custom value, how many are in use and how many jobs wait for one, plus the default, the ceiling and the global worker count. Slots are logical per-vCenter enrollment slots held from the start of an enrollment until the Agent's first heartbeat is reconciled; they are not simultaneous calls to vCenter and ESX hosts (bounded by the global workers) and not VIB verification workers. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

PUT
Enrollment Campaigns Api Update Vcenter Slots

Sets the custom number of enrollment slots of one vCenter, between 1 and the ceiling (default 20), or restores the default when slots is null. The value is stored with the vCenter's other settings, survives a restart, applies to the next admission and claim (also in campaigns that already exist), and is removed when the connection is removed. A value outside the bounds answers 400 CONCURRENCY_OUT_OF_RANGE and changes nothing. A change is recorded in the audit log as ENROLLMENT_CONCURRENCY_CHANGED with the slots before and after. Raising slots raises the load on that vCenter and on the Console; the recommended value is the default. Requires the ADMIN role.

POST
Enrollment Campaigns Api Start Campaign

A completed, cancelled or failed campaign cannot be started. Requires the ADMIN role.

POST
Enrollment Campaigns Api Pause Campaign

Only a running campaign can be paused. Requires the ADMIN role.

POST
Enrollment Campaigns Api Resume Campaign

Only a paused campaign can be resumed. Requires the ADMIN role.

POST
Enrollment Campaigns Api Cancel Campaign

Cancels the campaign. Requires the ADMIN role.

POST
Enrollment Campaigns Api Retry Failed Jobs

Re-queues the failed jobs of the campaign. Requires the ADMIN role.

Enterprise Sso
GET
Sso Settings Api Get Sso Settings

Returns the saved configuration, or the defaults when no row exists. The client secret, its ciphertext and its key id are never returned.

PUT
Sso Settings Api Update Sso Settings

A full replace. The ApiErrorResponse errorCode is one of: 400 INVALID_EXTERNAL_BASE_URL, EXTERNAL_BASE_URL_REQUIRED, DEFAULT_ROLE_NOT_ALLOWED, INVALID_CLOCK_SKEW, CLIENT_SECRET_REQUIRED_FOR_ISSUER_CHANGE and VALIDATION_FAILED; 409 ISSUER_CHANGE_CONFIRMATION_REQUIRED; 503 SSO_KEY_UNAVAILABLE (the master key is missing or unreadable while a client secret must be encrypted; nothing is saved). Disabling SSO or a confirmed issuer change revokes all active SSO sessions in the same transaction, including the acting administrator's own; the revocation audit reason is SSO_DISABLED or ISSUER_CHANGED respectively.

POST
Sso Settings Api Test Sso Discovery

A missing or non-https issuer is 400 VALIDATION_FAILED. Every fetch or parse failure is a 200 with ok=false and one stable problem code, never IdP-supplied text: DISCOVERY_FETCH_BLOCKED (blocked, unreachable or timed-out fetch; its fixed message says the address was refused or the request did not complete and that an operator can permit a private issuer host with VTP_OIDC_PRIVATE_ISSUER_HOSTS), DISCOVERY_ERROR_STATUS, DISCOVERY_NOT_JSON, DISCOVERY_ISSUER_MISMATCH, DISCOVERY_MISSING_FIELD and DISCOVERY_UNAVAILABLE. Only the discovery document is fetched. Nothing is persisted or revoked.

GET
Sso Settings Api List Sso Mappings

Returns a paginated collection of group mappings. q is a case-insensitive substring match on the IdP group. size is clamped to 1..100. sort accepts id, idpGroup, consoleRole or createdAt; any other property is 400 INVALID_SORT, and the default order is idpGroup ascending.

POST
Sso Settings Api Create Sso Mapping

400 VALIDATION_FAILED for an idpGroup that is missing or longer than 512 characters; a duplicate idpGroup is 409 OIDC_MAPPING_DUPLICATE. Group names are stored exactly as sent. Revokes all active SSO sessions in the same transaction, including the acting administrator's own, with reason MAPPING_CHANGED.

PUT
Sso Settings Api Update Sso Mapping

400 VALIDATION_FAILED for an invalid body; an unknown id is 404 OIDC_MAPPING_NOT_FOUND; a duplicate idpGroup is 409 OIDC_MAPPING_DUPLICATE. Revokes all active SSO sessions with reason MAPPING_CHANGED, even when the values are unchanged.

DELETE
Sso Settings Api Delete Sso Mapping

An unknown id is 404 OIDC_MAPPING_NOT_FOUND. Revokes all active SSO sessions with reason MAPPING_CHANGED.

Events
GET
Events Operations List

Searches security events by ingest time. With neither from nor to the window is the last 24 hours, with only one of them it is 24 hours on the other side of it. from must not be after to and the window must not exceed 30 days (400 INVALID_TIME_RANGE). page defaults to 0 and pageSize to 20 (1 to 100), a page that begins at row 50000 or later is refused (400 INVALID_PAGINATION), and the default sort is ingestTime DESC. severity filters one value, while severityMin and severityMax filter a range (severity supplies whichever bound is not given). agentId is the external agent identifier and agentPk the internal agent primary key, and when both are given both must match. An unknown eventClass, eventCategory, outcome, operation, sortBy or sortOrder, or a q shorter than 3 or longer than 100 characters after trimming, answers 400 INVALID_ARGUMENT. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Events Operations Get By Id

Returns the full detail of one event, with the reported rule when one was recorded. ingestTime is required, because the server uses it to prune the daily partitions, so send the ingestTime of the event as listed. A missing ingestTime or an id that is not a UUID answers 400, and 404 EVENT_NOT_FOUND when no event matches the id and ingestTime. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

File Catalog
GET
File Catalog Api List File Catalog

Lists the global file catalog, paginated, filterable and sortable. Accessible to every authenticated role.

GET
File Catalog Api Get File Catalog Entry

Returns the entry with the hypervisors that have the file. Accessible to every authenticated role.

POST
File Catalog Api Create File Rule

Creates a SHA-256 Rule (rank CUSTOM_GLOBAL) for the entry; the hash is taken from the entry, never from the request. The rule is attached to no Policy, so it enforces nothing until it is attached and published. Requires the ADMIN or SECURITY_OPERATOR role.

Groups
GET
Groups Api List Groups

Returns every Security Group. Accessible to every authenticated role.

POST
Groups Api Create Group

Also creates the mandatory empty published snapshot at policyVersion 1, atomically. Requires the ADMIN or SECURITY_OPERATOR role. Only ADMIN may send agentDisabledStatus true.

GET
Groups Api Get Group

Returns one Security Group by id with its name, description, whether it is the default Group, heartbeat interval, enforcement mode, agent-disabled status, policy version, whether it has pending changes, the number of hypervisors and Policies attached, and who created and last updated it. An unknown id returns 404 SECURITY_GROUP_NOT_FOUND. Accessible to every authenticated role.

PUT
Groups Api Update Group

When agentDisabledStatus changes, the Group's active agents are sent the disable or enable command after the change commits, in the background; the response does not wait for them. Requires the ADMIN or SECURITY_OPERATOR role. Only ADMIN may send agentDisabledStatus true.

DELETE
Groups Api Delete Group

Reassigns the Group's agents to the Default Group first, in one transaction. The Default Group cannot be deleted (DEFAULT_GROUP_UNDELETABLE). Requires the ADMIN or SECURITY_OPERATOR role.

GET
Groups Api List Group Policies

Returns the Policies attached to the Group in priority order. Accessible to every authenticated role.

POST
Groups Api Attach Policy

Requires the ADMIN or SECURITY_OPERATOR role.

PUT
Groups Api Sync Policies

Sets the Group's attached Policies to exactly the listed ones, adding, removing and reordering in one call (the Assign Policies flow). Requires the ADMIN or SECURITY_OPERATOR role.

DELETE
Groups Api Detach Policy

A 404 also covers a Policy that exists but is not attached to the Group. Requires the ADMIN or SECURITY_OPERATOR role.

PATCH
Groups Api Update Stack Rank

Requires the ADMIN or SECURITY_OPERATOR role.

GET
Groups Api Get Ssh Mfa Fallback

Accessible to every authenticated role. The Group's 'Require MFA for all SSH users' setting. It is on exactly when the shared Console-managed catch-all Policy (one Policy for all Groups) is attached to the Group. state separates saved from published: PENDING_ON and PENDING_OFF need a Group Publish, and neither says what a host has applied.

PUT
Groups Api Set Ssh Mfa Fallback

Idempotent. Never publishes: it attaches or detaches the shared managed Policy, which marks the Group as having pending changes. 409 MANUAL_CATCH_ALL_EXISTS when the Group already has an administrator-authored catch-all SSH MFA rule; 409 FALLBACK_NAME_CONFLICT when a reserved name is taken. Requires the ADMIN or SECURITY_OPERATOR role.

POST
Groups Api Publish Group

Compiles the Group's snapshot, advances policyVersion and clears hasPendingChanges. Requires the ADMIN or SECURITY_OPERATOR role.

GET
Groups Api Get Group Pending Changes

Compares the compiled staged state with the live published bundle. Read-only. Requires the ADMIN or SECURITY_OPERATOR role.

GET
Groups Api Get Agent Command Status

Counts, per delivery state, the agents of the Group that were sent the agent disable or enable command. Requires the ADMIN or SECURITY_OPERATOR role.

Hypervisor Mfa User Groups
GET
Hypervisor User Groups Api List Hypervisor User Groups

Returns a Spring Data Page of groups (ADMIN, SECURITY_OPERATOR or AUDITOR); the SSH MFA Rule wizard reads this list.

POST
Hypervisor User Groups Api Create Hypervisor User Group

Creates a group (ADMIN). 400 INVALID_HYPERVISOR_USER_GROUP; 409 DUPLICATE_GROUP_NAME.

GET
Hypervisor User Groups Api Get Hypervisor User Group

ADMIN, SECURITY_OPERATOR or AUDITOR. 404 HYPERVISOR_USER_GROUP_NOT_FOUND.

PUT
Hypervisor User Groups Api Update Hypervisor User Group

Renames or re-describes a group (ADMIN). 400 INVALID_HYPERVISOR_USER_GROUP; 404 HYPERVISOR_USER_GROUP_NOT_FOUND; 409 DUPLICATE_GROUP_NAME.

DELETE
Hypervisor User Groups Api Delete Hypervisor User Group

Deletes a group and its memberships (ADMIN). 409 GROUP_IN_USE while any SSH MFA Rule selects it; 404 HYPERVISOR_USER_GROUP_NOT_FOUND.

GET
Hypervisor User Groups Api List Hypervisor User Group Members

Members sorted by canonical username, unpaged. ADMIN only; any other role gets 403 FORBIDDEN (they see mfaIneligibleMemberCount on the group instead). 404 HYPERVISOR_USER_GROUP_NOT_FOUND.

POST
Hypervisor User Groups Api Add Hypervisor User Group Members

Adds users to a group (ADMIN); users already in the group are ignored. 400 INVALID_HYPERVISOR_USER_GROUP for an empty list or more than 1000 ids; 404 HYPERVISOR_USER_GROUP_NOT_FOUND or HYPERVISOR_USER_NOT_FOUND (nothing is added when any id is unknown).

DELETE
Hypervisor User Groups Api Remove Hypervisor User Group Member

Removes one member (ADMIN). 404 HYPERVISOR_USER_GROUP_NOT_FOUND or MEMBERSHIP_NOT_FOUND.

Hypervisor Mfa Users
GET
Hypervisor Users Api List Hypervisor Users

Returns a Spring Data Page of users. ADMIN only; any other role gets 403 FORBIDDEN. Carries no secret material.

POST
Hypervisor Users Api Create Hypervisor User

Creates a user in state PENDING (ADMIN). 400 INVALID_HYPERVISOR_USER; 409 DUPLICATE_USERNAME when the canonical name already exists (case-insensitive).

GET
Hypervisor Users Api Get Hypervisor User

ADMIN only; any other role gets 403 FORBIDDEN. 404 HYPERVISOR_USER_NOT_FOUND.

PUT
Hypervisor Users Api Update Hypervisor User

Updates profile data or the enabled flag (ADMIN). Changing enabled marks the affected Security Groups as having pending changes. 400 INVALID_HYPERVISOR_USER; 404 HYPERVISOR_USER_NOT_FOUND.

DELETE
Hypervisor Users Api Delete Hypervisor User

Deletes the user, its secrets and its memberships (ADMIN); Security Groups that delivered the user are marked as having pending changes. 404 HYPERVISOR_USER_NOT_FOUND.

POST
Hypervisor Users Api Enroll Hypervisor User

Issues the first secret (ADMIN); the user becomes ENROLLED. The response carries the seed once and is never cacheable (Cache-Control no-store). 409 ALREADY_ENROLLED unless the user is PENDING (use re-enroll); 503 MFA_KEY_UNAVAILABLE when no seed master key is available.

POST
Hypervisor Users Api Re Enroll Hypervisor User

Issues a new secret version (ADMIN); the previous version is superseded and kept only while a published revision pins it. Allowed from ENROLLED and REVOKED. Same no-store response as enroll. 409 NOT_ENROLLED while the user is PENDING; 503 MFA_KEY_UNAVAILABLE.

POST
Hypervisor Users Api Revoke Hypervisor User

Destroys the ciphertext of every secret version (ADMIN); the user becomes REVOKED and is never delivered again. Idempotent for an already REVOKED user. 409 NOT_ENROLLED while the user is PENDING.

POST
Hypervisor Users Api Import Hypervisor Users Csv

Creates PENDING users from a text/csv body (ADMIN). Header row required with a username column and optional displayName, email, identitySource (default LOCAL) and realm; header names are case-insensitive and underscores are ignored. At most 256 KiB and 1000 data rows; beyond either, 413 CSV_IMPORT_TOO_LARGE and nothing is imported. An empty body or a header without username is 400 INVALID_CSV. A duplicate canonical name is skipped and an invalid row is reported in errors; the remaining rows are created.

POST
Hypervisor Users Api Cancel Hypervisor User Enrollment

Deletes the active secret version and restores the previous one when it can be restored (ENROLLED), otherwise the user becomes REVOKED, or PENDING when there was no earlier version. Requires the ADMIN role.

Hypervisors
GET
Hypervisors Api List Hypervisors

Lists hypervisors of every management type, paginated, filterable and sortable. Accessible to every authenticated role.

GET
Hypervisors Api Get Facets

Distinct vCenter and cluster values across the whole persisted inventory, for filter drop-downs. Accessible to every authenticated role.

POST
Hypervisors Api Enroll Hypervisor

Starts agent enrollment for one hypervisor. The request body is optional. Requires the ADMIN role.

POST
Hypervisors Api Enroll Hypervisors Batch

Starts agent enrollment for each listed hypervisor and reports a result per host. Requires the ADMIN role.

POST
Hypervisors Api Reset Enrollment

Unenrolls the host and returns it to NOT_ENROLLED. The path /api/v1/hypervisors/{id}/unenroll is an alias of this operation. Requires the ADMIN role.

POST
Hypervisors Api Authorize Recovery

Releases the recovery marker left by a forced reset on fresh evidence from this request: the host's own Agent reports UNENROLLED in a read-only status check (AGENT_REPORTS_UNENROLLED), or no Agent answers and a live Agent software check conclusively finds the VIB uninstalled (VIB_NOT_INSTALLED). Neither is a signed confirmation or cryptographic proof: this is an administrative exception recorded with the operator and the reason. It unenrolls and releases nothing on the host, sends no command to the Agent, never enrolls the host and never re-enables Auto Enrollment. Every refusal changes nothing. Requires the ADMIN role: a signed-in Administrator, or an API token that has Full access, is owned by an Administrator and is allowed to write Hypervisors by the token route policy (the default is read only, so a token is refused until an administrator raises the Hypervisors family to Read and write). The audit event records the principal, its type (SESSION or API_TOKEN) and the token id, never the token secret. For a host whose vCenter connection a durable removal disabled (REMOVING or ATTENTION_REQUIRED), only the read-only Agent status check may use that connection, through a one-host status-probe grant that ends with the call; the Agent software check is not available then.

GET
Hypervisors Api Get Enrollment Status

Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
Hypervisors Api Sync Vib Inventory

Refreshes the agent VIB inventory, for one vCenter connection or for all. status is SERVICE_NOT_AVAILABLE when the inventory service is not configured. Requires the ADMIN role.

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

GET
Hypervisors Api List Active Agent Software Checks

Checks still running, oldest first; empty when none. Lets a reloaded page pick up a check. Jobs are held in memory only. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Hypervisors Api Get Agent Software Check

The job with each host's outcome from this run. Jobs are kept in memory: an unknown id, or a job from before a Console restart, answers 404, which the page reports as interrupted. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
Hypervisors Api Sync Single Vib Inventory

On 404 and 409 the body is HypervisorVibSyncResponse (status NOT_FOUND or SKIPPED with a message), not ApiErrorResponse. Requires the ADMIN role.

POST
Hypervisors Api Preflight Standalone Host

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

POST
Hypervisors Api Add Standalone Host

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

GET
Hypervisors Api List Standalone Hosts

Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

PUT
Hypervisors Api Update Standalone Certificate

Pins the certificate with the given SHA-256 fingerprint. Requires the ADMIN role.

DELETE
Hypervisors Api Remove Standalone Host

Removes a standalone ESXi host. A host that is enrolled or has an agent is first unenrolled remotely, and the removal is refused with 409 REMOTE_UNENROLL_FAILED when that remote unenrollment fails or cannot be confirmed, unless the force query parameter is true. A host that is not a standalone host returns 409 NOT_STANDALONE and an unknown id returns 404 HYPERVISOR_NOT_FOUND. The host record is deleted and its pinned certificate fingerprint is unregistered. Removal writes REMOVAL_STARTED and REMOVAL_OUTCOME lifecycle history rows and a HYPERVISOR_STANDALONE_REMOVE audit event (best effort, never blocking the removal). Requires the ADMIN role.

Licensing
GET
Licensing Operations Get Summary

Returns pooled entitlement, measured consumption and licensing lifecycle state. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Licensing Operations List Licenses

Returns every installed license with its serial number, product, validity dates, entitled cores, status (ACTIVE, EXPIRED or INVALID), the cores it contributes to the pool, import time, importing user and whether it can be deleted. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
Licensing Operations Import License

Imports a signed license file. A file for a serial number that is already installed replaces that license, in any state, and the answer is 200; a new serial number is installed and the answer is 201. A file with fewer cores or an earlier validTo than the installed one is not installed until the call is repeated with confirmDowngrade=true; the first call answers 409 LICENSE_UPDATE_REQUIRED_CONFIRMATION with the comparison and the resulting pool. The request body is the license file as text/plain, which is Base64 text that decodes to a 256-byte signature followed by the signed XML. The body must be valid UTF-8 and at most 65536 bytes (64 KB, counted in bytes). An empty, larger or non-UTF-8 body is rejected with 400 LICENSE_FORMAT_INVALID. A file whose format, certificate chain, signature, product, serial number, validity dates or cores are not valid is rejected with 400 and a stable license error code, and a license whose serial number or file is already installed is rejected with 409 LICENSE_DUPLICATE. ADMIN only.

DELETE
Licensing Operations Delete License

Deletes an installed license by serial number. ADMIN only. Not exempt from restricted mode (403 LICENSE_REQUIRED or LICENSE_EXPIRED while restricted). Deletable states are EXPIRED, NOT_YET_VALID and INVALID; an ACTIVE license returns 409 LICENSE_NOT_DELETABLE.

GET
Licensing Operations List Hosts

Returns paginated per-host core usage with calculation details. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Licensing Operations Export Usage

Returns a CSV export of per-host core usage as the text/csv response body (the code sets no explicit charset), sent as an attachment named hyperarmor-core-usage.csv. The file starts with seven comment lines that begin with a hash sign and give the evaluation time (ISO-8601 with offset), license state, entitled, consumed and available cores and the inactivity threshold in days. The column header row follows, in this order, hostname, vcenter, cpu_packages, physical_cores, minimum_applied, charged_cores, licensing_status, last_check_in_utc, topology_known, and then one row for every host. The hostname and vcenter values are always enclosed in double quotes with embedded quotes doubled, and a value that starts with =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The cpu_packages, physical_cores and last_check_in_utc cells are empty when the value is unknown. The same data is returned as a JSON object (evaluatedAt, licenseState, entitledCores, consumedCores, availableCores, inactivityThresholdDays and a hosts array of HostCoreUsageDto) when the request sends an Accept header that prefers application/json; the CSV is returned for text/csv, / or no Accept header, and any other Accept value gets a 406 NOT_ACCEPTABLE. The export takes no parameters, and the controller applies no filter, paging or row limit. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Licensing Operations Get Settings

Retrieves customer-controlled licensing configuration. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

PUT
Licensing Operations Update Settings

Updates customer-controlled licensing configuration (ADMIN only).

Policies
GET
Policies Api List Policies

Lists Policies, paginated, searchable and sortable. Accessible to every authenticated role.

POST
Policies Api Create Policy

Requires the ADMIN or SECURITY_OPERATOR role.

GET
Policies Api Get Policy

Returns one Policy by id with its name, description, the number of Groups and Rules attached, the number of attached Groups with pending changes, the published version, whether it has unpublished changes, and who created and last updated it. An unknown id returns 404 POLICY_NOT_FOUND. Accessible to every authenticated role.

PUT
Policies Api Update Policy

Requires the ADMIN or SECURITY_OPERATOR role.

DELETE
Policies Api Delete Policy

Removes the Policy and its Rule attachments. Refused while the Policy is attached to any Group (POLICY_STILL_ATTACHED) and for the baseline Policy (BASELINE_POLICY_UNDELETABLE). Requires the ADMIN or SECURITY_OPERATOR role.

GET
Policies Api List Policy Rules

Returns the Rules attached to the Policy in evaluation order. Accessible to every authenticated role.

POST
Policies Api Attach Rule

Appends the Rule at sequence max+1. 409 RULE_ALREADY_ATTACHED when already attached, 409 RULE_RETIRED for a retired Built-in Rule. Requires the ADMIN or SECURITY_OPERATOR role.

PUT
Policies Api Sync Rules

Sets the Policy's attached Rules to exactly the listed ones (the Assign Rules flow). 409 RULE_RETIRED when the list adds a retired Built-in Rule the Policy does not already contain; keeping or removing an existing link to one is allowed. Nothing changes when the request is refused. Requires the ADMIN or SECURITY_OPERATOR role.

GET
Policies Api List Policy Groups

Every Group the Policy is attached to. Accessible to every authenticated role.

GET
Policies Api Get Policy Pending Changes

Compares the Policy's enabled rules compiled now with its published snapshot. Read-only. Requires the ADMIN or SECURITY_OPERATOR role.

DELETE
Policies Api Detach Rule

A 404 also covers a Rule that exists but is not attached to the Policy. Requires the ADMIN or SECURITY_OPERATOR role.

PATCH
Policies Api Reorder Rules

The sequence is evaluation-significant. The list must be exactly the Policy's current attached Rule set (RULE_SET_MISMATCH otherwise). Requires the ADMIN or SECURITY_OPERATOR role.

POST
Policies Api Publish Policy

Compiles the Policy's enabled rules, in sequence order, as its new published snapshot, bumps publishedVersion and clears hasUnpublishedChanges. Every bound Group is marked as needing a publish; no Group is published and no agent receives anything. Requires the ADMIN or SECURITY_OPERATOR role.

Reports
GET
Reports Operations Get File Approvals Preview

Returns summary metrics for file approvals within the specified time range. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Reports Operations Export File Approvals

Streams a CSV export of active catalog file approval entries. The response is text/csv with charset UTF-8, sent as an attachment named file-approvals-report-YYYY-MM-DD.csv (the date is the current UTC date) with caching disabled. The first line is the column header row, in this order, file_id, sha256, file_name, file_kind, global_state, hypervisor_count, rule_attached, first_catalogued, new_in_range, publisher. There is one row for every catalog file that has at least one presence record, ordered by file_id, and the range does not filter the rows, it only sets new_in_range to true for files first catalogued inside the window. The sha256 value is lowercase hex and first_catalogued is an ISO-8601 UTC instant. Text columns (sha256, file_name, file_kind, global_state, first_catalogued, publisher) are always enclosed in double quotes with embedded quotes doubled, and a text value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The range query parameter accepts 24h, 7d or 30d and defaults to 7d, and any other value is rejected with 400 INVALID_RANGE. There is no row limit. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403, although it may use the preview). Every export attempt is audited (REPORT_EXPORTED on success, REPORT_EXPORT_FAILED on a denied or failed attempt).

GET
Reports Operations Get Policy Effectiveness Preview

Returns configuration health and top policy match volume metrics. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Reports Operations Export Policy Effectiveness

Streams a CSV export of policy match volume and configuration health. The response is text/csv with charset UTF-8, sent as an attachment named policy-effectiveness-report-YYYY-MM-DD.csv (the date is the current UTC date) with caching disabled. The first line is the column header row, in this order, policy_id, policy_name, description, has_unpublished_changes, groups_bound, rule_count, matched_events. There is one row for every policy regardless of the range, ordered by matched_events descending and then by policy name, and the range only limits matched_events to events ingested inside the window that matched one of the policy's rules. The policy_name and description columns are always enclosed in double quotes with embedded quotes doubled, and a text value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The range query parameter accepts 24h, 7d or 30d and defaults to 7d, and any other value is rejected with 400 INVALID_RANGE. There is no row limit. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403, although it may use the preview). Every export attempt is audited (REPORT_EXPORTED on success, REPORT_EXPORT_FAILED on a denied or failed attempt).

GET
Reports Operations Get Ssh Mfa Preview

Returns count of SSH challenges and challenged hypervisors. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Reports Operations Export Ssh Mfa

Streams a CSV export of hypervisors with SSH MFA challenges. The response is text/csv with charset UTF-8, sent as an attachment named ssh-mfa-report-YYYY-MM-DD.csv (the date is the current UTC date) with caching disabled. The first line is the column header row, in this order, hostname, challenged_events, denied_events, last_denied. There is one row for each agent host that has at least one SSH MFA event ingested inside the range window, ordered by challenged_events descending and then by hostname. The challenged_events column counts the CHALLENGED and ALLOWED outcomes, denied_events counts the CHALLENGE_FAILED and PREVENTED outcomes, and last_denied is the ISO-8601 UTC time of the latest denied event (an empty quoted value when there is none). The hostname and last_denied columns are always enclosed in double quotes with embedded quotes doubled, and a text value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The range query parameter accepts 24h, 7d or 30d and defaults to 7d, and any other value is rejected with 400 INVALID_RANGE. There is no row limit. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403, although it may use the preview). Every export attempt is audited (REPORT_EXPORTED on success, REPORT_EXPORT_FAILED on a denied or failed attempt).

GET
Reports Operations Get Protection Coverage Preview

Returns counts of prevented and observed events and protected hypervisors. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
Reports Operations Export Protection Coverage

Streams a CSV export of protection events by rule. The response is text/csv with charset UTF-8, sent as an attachment named protection-coverage-report-YYYY-MM-DD.csv (the date is the current UTC date) with caching disabled. The first line is the column header row, in this order, rule_name, rule_guid, rule_rank, rule_deleted, prevented_events, observed_events, hypervisors_affected, first_event, last_event. There is one row for each matched rule among the events ingested inside the range window with the outcome PREVENTED, TERMINATED or DETECTED_OBSERVE, ordered by total event count descending. The prevented_events column counts the PREVENTED and TERMINATED outcomes and observed_events counts DETECTED_OBSERVE. Events whose rule no longer exists appear as (unavailable Rule) with rule_deleted true, and events with no matched rule appear as (no matched Rule). The text columns (rule_name, rule_guid, rule_rank, first_event, last_event) are always enclosed in double quotes with embedded quotes doubled, and a text value whose first non-space character is =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The range query parameter accepts 24h, 7d or 30d and defaults to 7d, and any other value is rejected with 400 INVALID_RANGE. There is no row limit. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403, although it may use the preview). Every export attempt is audited (REPORT_EXPORTED on success, REPORT_EXPORT_FAILED on a denied or failed attempt).

Rules
GET
Rules Api List Rules

Lists every Rule (Built-in and Custom), paginated, filterable and sortable. Accessible to every authenticated role.

POST
Rules Api Create Rule

Creates a Custom Rule. minAgentVersion is never accepted. A missing or blank ruleType is 400 UNKNOWN_RULE_TYPE (ruleType is required); a matchData longer than 8192 characters is 400 INVALID_MATCH_DATA. Requires the ADMIN or SECURITY_OPERATOR role.

GET
Rules Api List Rule Ids

Ids of the Rules that match the same filters as the Rules list, with no page parameters, so a client can select every match across pages. Returns at most 500 ids (the most Rules one Policy can have attached) in the requested order, and truncated is true when more match. With assignable=true retired Rules are left out, because a Policy refuses them with 409 RULE_RETIRED. Read-only. Accessible to every authenticated role.

GET
Rules Api Get Rule

Returns one Rule by id with its type, match data, action, rank, minimum agent version, guid, enabled and built-in flags, revision, the number of Policies it is attached to, and who created and last updated it. An unknown id returns 404 RULE_NOT_FOUND. Accessible to every authenticated role.

PUT
Rules Api Update Rule

Edits a Custom Rule's own content. 409 BUILT_IN_RULE_IMMUTABLE for a Built-in Rule. For a file-catalog rule (CUSTOM_GLOBAL) the SHA-256 cannot change: 409 RULE_HASH_LOCKED. A matchData longer than 8192 characters is 400 INVALID_MATCH_DATA. Saving the values the Rule already has (after the name and description are trimmed and matchData is normalized) changes nothing: 200 with the Rule as it is, the same revision, its Policies keep their published state and no RULE_UPDATE audit record is written. Requires the ADMIN or SECURITY_OPERATOR role.

DELETE
Rules Api Delete Rule

A Rule that Policies still use is first detached from each of them in the same transaction (each such Policy is flagged as having unpublished changes). Nothing is published, so Policy snapshots and Groups still carry the Rule until published. 409 BUILT_IN_RULE_IMMUTABLE for a Built-in Rule. Requires the ADMIN or SECURITY_OPERATOR role.

GET
Rules Api List Rule Policies

Every Policy the Rule is attached to. Accessible to every authenticated role.

PATCH
Rules Api Set Rule Enabled

Toggles isEnabled on a User-defined Rule. A Built-in Rule is always enabled: disabling one is refused (409 BUILT_IN_RULE_CANNOT_BE_DISABLED). Requires the ADMIN or SECURITY_OPERATOR role.

GET
Rule Pack Api Status

The installed Rule Pack (the install with the highest packSequence, or installed null when none is installed) and feed, the portal check. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
Rule Pack Api Review Upload

Verifies and diffs an uploaded pack (source UPLOAD) and stores the review for 7 days, replacing every other stored review. Installing it is a separate call. A request that is not multipart/form-data answers 415. Requires the ADMIN role.

POST
Rule Pack Api Download

Downloads the pack from the portal URL stored in the database and reviews it as an upload, with source FEED. No request body. The saved token, if any, is sent as a Bearer token to the portal host only. Requires the ADMIN role.

POST
Rule Pack Api Check Now

Runs the portal check at once, verify-only: it never stores a review and never installs. No request body. A check that fails still answers 200, with the failure in error. A check within 30 seconds of the last one is not repeated and the current feed is returned. Requires the ADMIN role.

GET
Rule Pack Api Feed Settings

Never returns the download URL or the token. Requires the ADMIN role.

PUT
Rule Pack Api Update Feed Settings

The token is write-only and is stored encrypted. The download URL cannot be set through the API. Requires the ADMIN role.

DELETE
Rule Pack Api Discard Review

Idempotent: 204 whether or not a stored review had this reviewId. Requires the ADMIN role.

POST
Rule Pack Api Install

Installs the stored review in one transaction after verifying the stored files again. Changes Rule rows only: no Policy is marked unpublished and nothing is published. Requires the ADMIN role.

Settings
GET
General Settings Operations Get

Settings shown on the General tab. Readable by every authenticated role.

PUT
General Settings Operations Update Retention

Save the retention values. ADMIN only. Applied by the next nightly maintenance run.

GET
Api Token Policy Operations Get

Read the token route policy. ADMIN session, or an ADMIN Full-access Bearer API token while tokenCanManagePolicy is on.

PUT
Api Token Policy Operations Update

Change the mode of route families. ADMIN session, or an ADMIN Full-access Bearer API token while tokenCanManagePolicy is on; tokenCanManagePolicy itself can be changed by an ADMIN session only. Audited as API_TOKEN_POLICY_UPDATED.

Syslog Destinations
GET
Syslog Forwarders List

Returns all configured Syslog forwarding destinations (maximum 2 destinations system-wide). Accessible to ADMIN, SECURITY_OPERATOR, and AUDITOR.

POST
Syslog Forwarders Create

Configures a new outbound Syslog forwarding destination (max 2 destinations system-wide). Initializes watermark to now - 5 minutes. Validates destination host/port against SSRF rules. Requires ADMIN role.

GET
Syslog Forwarders Get By Id

Retrieves full configuration profile and telemetry statistics for a specific Syslog forwarder. Accessible to ADMIN, SECURITY_OPERATOR, and AUDITOR.

PUT
Syslog Forwarders Update

Updates configuration parameters of an existing Syslog forwarder. Supports optimistic concurrency check via expectedVersion. Requires ADMIN role.

DELETE
Syslog Forwarders Delete

Deletes a Syslog forwarder profile and cascades deletion to its associated watermark. Requires ADMIN role.

POST
Syslog Forwarders Test Existing

Performs a synchronous DNS resolution, network socket connect, and optional TLS handshake probe against an existing forwarder profile. Updates lastTestAt, lastTestStatus, and lastErrorMessage on the forwarder record. Requires ADMIN role.

POST
Syslog Forwarders Test Unsaved

Performs a synchronous reachability test on unsaved destination parameters before creating or updating a forwarder profile. Subject to SSRF validation. Requires ADMIN role.

Telemetry
GET
Telemetry Settings Api Get Telemetry Settings

Telemetry settings. Readable by every authenticated role.

PUT
Telemetry Settings Api Update Telemetry Settings

Save telemetry settings. ADMIN only. Changing shareAdditionalData is not retroactive.

POST
Telemetry Settings Api Acknowledge Telemetry Disclosure

Record that the disclosure notice was acknowledged. ADMIN only. Informational; gates no upload.

GET
Telemetry Api Get Telemetry Status

Current reporting status. Readable by every authenticated role.

GET
Telemetry Api List Telemetry Reports

Stored reports, newest first. Readable by every authenticated role.

GET
Telemetry Api Download Telemetry Report

Exact stored report for a day (attachment vtp-usage-DATE.json). Readable by every authenticated role; audited.

GET
Telemetry Api Get Telemetry Preview

Preview of today's report so far, by tier. ADMIN only. Nothing is stored or sent.

POST
Telemetry Api Send Telemetry Now

Trigger an upload cycle. ADMIN only. Globally throttled to 1 per minute. Takes no request body; a body that is sent must be well-formed JSON (it is otherwise ignored), or the request is refused with 400, or with 415 when its Content-Type is not JSON.

User Management
GET
Users Operations List

Returns a paginated collection of console user summaries matching query criteria.

POST
Users Operations Create

Creates a console user with a role and an initial LOCAL password; the account must change that password on first login.

GET
Users Operations Get By Id

Returns full detail for a single console user account.

PUT
Users Operations Update

Updates a console user's display name, email, role, or status; the protected default administrator's role and status cannot be changed.

DELETE
Users Operations Delete

Permanently deletes a console user account; the protected default administrator account cannot be deleted.

DELETE
Users Operations Revoke Sessions

Audited OIDC_SESSIONS_REVOKED for an SSO user and USER_SESSIONS_REVOKED for a local user. Answers 204 whether or not the user has an active session, and 404 USER_NOT_FOUND for an unknown id. When the target is the caller, every session except the caller's current one is revoked.

POST
Users Operations Reset Password

Requires the ADMIN role, a LOCAL administrator account and an interactive console session. The caller reauthenticates with its own current password (adminPassword). The target gets the temporary password, must change it at its next sign-in, and every one of its sessions is revoked. Refused for the caller's own account (use POST /api/v1/auth/change-password), for the protected default administrator (its password is set with the appliance recovery script /opt/vmhyperarmor/bin/vmhyperarmor-admin-password) and for SSO accounts. Five wrong administrator passwords within 15 minutes block further resets by that administrator until the window ends. Audited as USER_PASSWORD_RESET, on success and on failure, never with a password.

User Preferences
GET
Preferences Operations Get Preferences

Returns all personal preferences (such as table column customisations) for the authenticated user. Accessible to every authenticated role. The path /api/v1/users/preferences is an alias of /api/v1/user/preferences for every method. The result is one JSON object keyed by preference key, empty when nothing is stored; a stored value that does not parse as JSON is returned as its raw string.

POST
Preferences Operations Set Preferences

Persists or merges user preferences for the authenticated user. Accessible to every authenticated role. The path /api/v1/users/preferences is an alias of /api/v1/user/preferences for every method. Preference keys are free-form (no allow-list; 1 to 256 characters, the console itself uses names such as tabs., panels. and dashboard.layout.v1); keys that are blank are ignored, any JSON value is accepted for a key, and a value equal to the stored one is not rewritten. Keys not named in the body are kept. The 200 response is the complete preference set of the user after the update.

PUT
Preferences Operations Update Preferences

Persists or merges user preferences for the authenticated user; behaves like POST. The path /api/v1/users/preferences is an alias of /api/v1/user/preferences for every method. Accessible to every authenticated role. The same rules apply: keys are free-form (1 to 256 characters), blank keys are ignored, any JSON value is accepted, an unchanged value is not rewritten, keys not named in the body are kept, and the 200 response is the complete preference set after the update.

DELETE
Preferences Operations Delete All

Resets all stored user preferences to their default states. Accessible to every authenticated role. The path /api/v1/users/preferences is an alias of /api/v1/user/preferences for every method. Answers 204 also when no preference is stored.

GET
Preferences Operations Get By Key

Returns the stored value of a specific preference key. Accessible to every authenticated role. The path /api/v1/users/preferences/{key} is an alias of /api/v1/user/preferences/{key} for every method. The value is returned as parsed JSON of any type, or as the raw string when it was stored but is not JSON.

DELETE
Preferences Operations Delete By Key

Deletes a specific preference key for the authenticated user. Accessible to every authenticated role. The path /api/v1/users/preferences/{key} is an alias of /api/v1/user/preferences/{key} for every method. Answers 204 whether or not the key is stored.

V Center Connections
GET
VCenter Connections List

Returns all configured vCenter connections with connection and trust health metadata. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
VCenter Connections Save

Persists a tested and verified vCenter connection with authoritative instance UUID and certificate trust material. Requires the ADMIN role.

DELETE
VCenter Connections Delete

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.

POST
VCenter Connections Inspect Certificate

Reads the certificate the endpoint presents using only its host name and port. No username, password or token is accepted or sent. When the certificate needs an administrator decision the response carries a single-use trustChallengeId that Test Connection then uses to pin exactly that certificate. Loopback, link-local and multicast targets are refused, concurrent inspections are limited, and pending approvals are bounded. Requires the ADMIN role.

POST
VCenter Connections Test Connection

Diagnostic probe testing strict TLS trust, credential validity, and instance UUID. Requires the ADMIN role.

POST
VCenter Connections Accept Trust Challenge

Consumes a single-use trustChallengeId, establishes EXACT_PIN connection, verifies credentials, and mints verifiedConnectionToken. Requires the ADMIN role.

GET
VCenter Connections Get Offboarding Summary

Counts the hosts and agents tied to the connection and lists the recovery outcome per host. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
VCenter Connections Get Removal

Reads the latest removal operation of the connection from the database, so it is available after a Console restart and after the connection row was deleted. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
VCenter Connections Get Removal By Id

Reads one removal operation. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

GET
VCenter Connections List Removal Hosts

Pages the hosts of a removal, hosts needing attention first, then by host key. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

POST
VCenter Connections Retry Removal

Starts generation g+1 of a stopped removal for the incomplete hosts only. Hosts already confirmed are never signed again. The pass runs in the background; follow it with GET removal. Requires the ADMIN role.

POST
VCenter Connections Abandon Local Removal

Exceptional, explicitly authorized local retirement. It removes the Console records only. Hosts without a confirmed outcome become LOCAL_ABANDONED, Agent ownership history, the unconfirmed-offboarding evidence and the suppression of automatic enrollment are kept, and no host is reported unenrolled. It never authorizes enrolling the host here or in another Console. Allowed only from ATTENTION_REQUIRED after at least one retry. Requires the ADMIN role.

POST
VCenter Connections Confirm Inventory Hold

A complete vCenter snapshot that would remove an empty or unusually large share of the connection's current hosts is not applied: the hosts it lists are updated and removal is held (inventoryHoldReason on the connection). This operation lets an administrator accept the removal. observedHostCount must equal inventoryHoldObservedHosts and holdId must equal inventoryHoldId. The audit record VCENTER_INVENTORY_REMOVAL_CONFIRMED is written first and the confirmation is armed only after that transaction commits. The worker re-reads the whole inventory on its next baseline (after the running long poll returns, up to about 90 seconds) and removes the missing hosts only if that new snapshot lists exactly the held hosts (same host set, not just the same count), the known host count is unchanged, the same vCenter is read and the confirmation has not expired (vtp.discovery.prune-guard.confirmation-ttl-minutes, default 10); the confirmation is single use and is cleared by any failure, stop or replacement hold, in which case the removal is held again with a new inventoryHoldId. A non-numeric id returns 400 INVALID_CONNECTION_ID, a missing or negative count 400 INVALID_OBSERVED_HOST_COUNT, a missing or blank holdId 400 INVALID_HOLD_ID, an unknown connection 404 CONNECTION_NOT_FOUND, no held removal 409 INVENTORY_HOLD_NOT_ACTIVE, a holdId that is not the current hold's (the hold changed since it was shown) 409 INVENTORY_HOLD_STALE and a different count 409 INVENTORY_HOLD_COUNT_MISMATCH. Requires the ADMIN role.

PUT
VCenter Connections Update Credentials

Replaces the stored password (and optionally the display name) of an existing vCenter connection without deleting it, so the discovered inventory and Agent ownership are kept. The new password is first verified live against the endpoint with the pinned certificate and the stored instance UUID; if the endpoint answers as a different vCenter instance, or the certificate is no longer the pinned one, nothing is changed. Host, port, username, pinned certificate and instance UUID cannot be changed here. Requires the ADMIN role.

POST
VCenter Connections Create Retrust Challenge

Opens a TLS handshake to the connection's host and port only to read the presented leaf certificate; no credential is sent. When it differs from the pinned certificate a single-use trustChallengeId is returned for use with PUT trusted-certificate. An expired or not-yet-valid certificate is never offered. Requires the ADMIN role.

PUT
VCenter Connections Retrust Certificate

Replaces the pinned certificate after the administrator echoes the fingerprints of the old and the new certificate, re-enters the vCenter password and confirms. The new certificate is pinned exactly and the same vCenter instance UUID must answer before anything is stored; trust is replaced atomically, both fingerprints are audited, the source restarts with the new trust and, if it cannot restart, the previous trust is restored. A challenge is single-use and bound to the connection's endpoint. Requires the ADMIN role.

PUT
VCenter Connections Set Auto Enrollment

Turns automatic enrollment of the hosts of this vCenter connection on or off. The required enabled query parameter is stored as a per-connection setting that the auto-enrollment campaign producer reads, and the response is the connection with its autoEnrollmentEnabled value. The id is the numeric connection id (a db- prefix is also accepted). A non-numeric id returns 400 INVALID_CONNECTION_ID and an unknown connection returns 404 CONNECTION_NOT_FOUND. Requires the ADMIN role.