HyperArmor API Documentation
Canonical browser-to-server HTTP API contracts for HyperArmor. This page is read-only documentation: Try it out is disabled.
Authentication
- Sign in with
POST /api/v1/auth/login. The service sets anHttpOnlyVTP_SESSIONcookie and anXSRF-TOKENcookie. - Send the session cookie on every other operation.
- On every
POST,PUT,PATCHandDELETE, also echo theXSRF-TOKENcookie value in theX-XSRF-TOKENheader.
Scripts and integrations can instead send an API token as Authorization: Bearer <token> (no cookie or XSRF header). A token is accepted on the route families the administrator's token route policy allows (GET /api/v1/settings/api-token-policy; by default Alerts, Groups, Policies, Rules, Files, Alert rules, Endpoints and read-only Hypervisors, Events, Dashboard, Deployment, Reports and Audit Logs); only the operations that list bearerAuth are marked here, and every other route answers 403 API_TOKEN_NOT_PERMITTED. A Read-only token may call the reads, a Full token the actions as well. The documentation page /api/v1/docs/ and this contract at /api/v1/docs/openapi.yaml accept a Bearer token too (GET and HEAD only, any access level).
Using this page with an API token. This page is documentation only: Try it out is disabled and the page cannot send any request, so the Authorize dialog does not call the API from here. If you open it, paste only the token (the vtp_ value, without the word Bearer). To call the API with a token, use curl, Postman or Insomnia and send Authorization: Bearer <token>. A browser without a console session cannot open this page or openapi.yaml; to read either without a browser login, send the same Authorization: Bearer header from curl, Postman or Insomnia (any valid token works, READ_ONLY is enough).
Errors
| Status | errorCode |
When |
|---|---|---|
| 401 | UNAUTHENTICATED |
The session is missing, expired or revoked. |
| 403 | FORBIDDEN |
The caller's role may not perform the operation. |
| 403 | CSRF_ERROR |
The X-XSRF-TOKEN header is missing or wrong. |
| 403 | PASSWORD_CHANGE_REQUIRED |
The account must change its password. Every operation except session, logout and change-password is blocked. |
| 403 | LICENSE_REQUIRED |
No valid license is installed (NO_LICENSE). Most operations are blocked. |
| 403 | LICENSE_EXPIRED |
The licence pool is RESTRICTED (expired past grace). Most operations are blocked. |
| 429 | none | Repeated authentication attempts are limited by the gateway. The response is plain, with no JSON body. |
All other errors use the ApiErrorResponse body.
Pagination
Paged lists use a zero-based page index: the first page is 0. The page-size parameter is pageSize on most operations and size on the five Spring Data lists (users, audit-logs, SSO mappings, hypervisor-users, hypervisor-user-groups); audit-logs also accepts pageSize as an alias that replaces size. The response envelopes are not unified; the four shapes are named in the last column. On the Spring Data lists a negative page is expected to be treated as 0 by Spring Data instead of answering an error (the console does not check it itself). Where a parameter's text says a value is capped or clamped, the schema bounds show the useful range: the server accepts a value outside it and corrects it, where a strict client or generated client would reject it.
| Operations | Page size parameter | Default and limits | Outside the limits | Response |
|---|---|---|---|---|
| endpoints, events, alerts/search, file-catalog, hypervisors, policies, rules | pageSize |
20, 1 to 100 | 400 INVALID_PAGINATION, also for a negative page |
PaginatedResponse_<Item> (items, page, pageSize, totalItems, totalPages) |
| users | size |
20, up to 100 | a size above 100 answers 400 INVALID_PAGE_SIZE |
PaginatedResponse_UserSummaryDto |
| SSO mappings | size |
20, up to 100 | a size above 100 is clamped to 100 | PaginatedResponse_SsoGroupMapping |
| audit-logs | size, alias pageSize |
20, size up to 200, pageSize up to 100 |
a larger value is capped, not rejected | PaginatedResponse_AuditLogSummaryDto |
| hypervisor-users, hypervisor-user-groups | size |
20, up to 200 | a larger size is capped at 200 | SpringPage_<Item> (content, totalElements, totalPages, number, size and more) |
| api-tokens | size |
20, 1 to 100 | a size outside 1 to 100 answers 400 INVALID_PAGE_SIZE |
SpringPage_ApiTokenOverviewDto |
| licensing/hosts | pageSize |
25, 1 to 200 | clamped into the range; a negative page becomes 0 |
HostCoreUsagePage (items, page, pageSize, totalItems) |
| telemetry/reports | pageSize |
20, 1 to 100 | pageSize below 1 answers 400 INVALID_PAGE_SIZE, above 100 is clamped to 100; a negative page answers 400 INVALID_PAGE |
TelemetryReportPageDto (items, page, pageSize, totalItems) |
Sorting. The lists of the first row of the table take sortBy and sortOrder (ASC or DESC); an unknown value answers 400 INVALID_SORT, except events (INVALID_ARGUMENT) and file-catalog (INVALID_FILTER). The Spring Data lists take sort as property,direction (for example occurredAt,desc); audit-logs, SSO mappings and hypervisor-users answer 400 INVALID_SORT for a property outside the list in the parameter text, while users and hypervisor-user-groups publish no list, so use an attribute of the listed item. Licensing hosts takes sort as field,asc or field,desc over hostname, chargedCores and licensingStatus; any other field falls back to hostname.
Events can be paged only through the first 50000 rows of a result: a page that begins at row 50000 or later answers 400 INVALID_PAGINATION, and totalItems is capped at 50000 and totalCapped is true when more rows matched than the cap, so totalItems is then a lower bound.
Lists with a limit and lists without paging. GET /api/v1/alerts takes limit (default 50, at most 200; a larger value is capped and zero or a negative value is replaced by 50) and returns items only. GET /api/v1/dashboard/top-matched-rules takes limit (default 5, 1 to 10, otherwise 400 INVALID_ARGUMENT) and window (24h, 7d or 30d). GET /api/v1/vcenter-connections and GET /api/v1/agents/{agentPk}/commands are not paged.
Naming
Operation summaries start with Get rather than Retrieve, Fetch or Read when they read one resource. Parameter names are camelCase and are the names the server binds. operationId values keep their generated <Interface>_<method> form, and property names, enum values and error codes are part of the contract and are not renamed.