API schemas: A

About

Service information.

Name	Type	Required	Description
`apiVersion`	`string`	yes	API version.
`isLeader`	`boolean`	yes	Whether this node is the leader.
`name`	`string`	yes	Product name.
`nodeId`	`integer` (int64)	yes	Store node id.
`records`	`integer`	yes	Number of records.
`storeVersion`	`integer` (int64)	yes	Current store version.
`uptimeSeconds`	`integer` (int64)	yes	Uptime in seconds.
`version`	`string`	yes	Build version.

AcknowledgeRequest

Acknowledge request.

Name	Type	Required	Description
`targetId`	`string`	yes	Entity whose state is acknowledged.

ActionView

Rule action.

Values: "allow", "drop", "reject", "pass"

AddHostRequest

Body for POST /v1/clusters/{id}/hosts (AddHost_Task).

Name	Type	Required	Description
`force`	`boolean` or `null`		When true, return an existing same-name host instead of failing; a registered host in this cluster is reset (its certificate revoked) so its agent can join again with the join token.
`managementAddress`	`string` or `null`		Optional management address; defaults to `name`.
`name`	`string`	yes	Host display name / FQDN (must match the agent's `hostname` at join).

AddUpdateSessionFileRequest

Add a PUSH file to an update session.

Name	Type	Required	Description
`name`	`string`	yes	File name (basename, e.g. `ubuntu.iso`).
`size`	`integer` (int64) or `null`		Optional expected size in bytes.
`sourceType`	`string`		Source type; only `PUSH` is supported.

AddressSince

An address and when it was allocated.

Name	Type	Required	Description
`address`	`string`	yes	The address.
`since`	`string`	yes	Allocation time.

AlarmAction

What an alarm does when it changes status.

One of: object, object

AlarmStateView

Alarm state on one entity.

Name	Type	Required	Description
`acknowledged`	`boolean`	yes	Acknowledged.
`since`	`string`	yes	Since.
`status`	`AlarmStatusView`	yes	Status.
`targetId`	`string`	yes	Entity id.

AlarmStatus

Alarm status (ManagedEntityStatus).

Values: "gray", "green", "yellow", "red"

AlarmStatusView

Alarm status.

Values: "gray", "green", "yellow", "red"

AlarmTrigger

What raises an alarm.

One of: object, object

AlarmView

An alarm definition with states.

Name	Type	Required	Description
`actions`	array of `AlarmAction`		Actions.
`description`	`string`	yes	Description.
`enabled`	`boolean`	yes	Enabled.
`id`	`string`	yes	Alarm id.
`name`	`string`	yes	Name.
`scopeId`	`string`	yes	Scope entity id.
`states`	array of `AlarmStateView`	yes	Per-entity states.
`trigger`	`AlarmTrigger`	yes	Trigger definition.
`version`	`integer` (int64)		Record version, for `expectedVersion` of `PUT /v1/alarms/{id}`.

AllocateBody

Allocate an address.

Name	Type	Description
`address`	`string` or `null`	A specific IPv4 address.
`family`	`string` or `null`	`ipv4` (default) or `ipv6` (a /64).
`mac`	`string` or `null`	NIC MAC (absent: the VM's first NIC on the pool's network).
`reference`	`string` or `null`	Caller reference.
`role`	`string` or `null`	`primary` (default) or `extra`.
`tenant`	`string` or `null`	Tenant (quota).
`vm`	`string` or `null`	VM to bind to (absent: reserved for the tenant).

AllocationView

One address of a pool: allocated or in quarantine.

Name	Type	Required	Description
`address`	`string`	yes	IPv4 address, or the /64 (`prefix/64`).
`allocatedAt`	`string` or `null`		Allocation time.
`family`	`string`	yes	`ipv4` or `ipv6`.
`mac`	`string` or `null`		Bound NIC MAC.
`ptr`	`string` or `null`		Reverse DNS name.
`ptrReason`	`string` or `null`		Why the operator rejected the name.
`ptrStatus`	`string` or `null`		`applied`, `requested`, `rejected`, or `to_remove` (a released address whose PTR an operator must remove; status `released`).
`quarantinedUntil`	`string` or `null`		End of the quarantine.
`reference`	`string` or `null`		Caller reference.
`role`	`string` or `null`		`primary` or `extra` (IPv4).
`status`	`string`	yes	`allocated` or `quarantined`.
`tenant`	`string` or `null`		Tenant.
`vm`	`string` or `null`		Bound VM.

ApiInfoView

OpenAPI stand-in for GET /v1/backup/info (ApiInfo).

Name	Type	Required	Description
`apiVersion`	`string`	yes	API version string (`1.0`).
`features`	array of `BackupFeatureView`	yes	Features the service advertises.
`granularity`	`integer` (int64)	yes	Default tracking granularity in bytes.
`maxAreasPerPage`	`integer` (int64)	yes	Largest `maxAreas` accepted.
`maxTtlSeconds`	`integer` (int64)	yes	Longest session TTL in seconds.
`remoteExports`	`boolean`	yes	Whether exports are reachable off-host (TCP with TLS).

ApiTokenView

An API token without its secret.

Name	Type	Required	Description
`createdAt`	`string`	yes	Creation time.
`expiresAt`	`string` or `null`		Expiry.
`id`	`string`	yes	Public id (16 hex characters, also inside the token).
`lastUsed`	`string` or `null`		Last use.
`name`	`string`	yes	Label.

ApplyTemplateBody

Body of POST /v1/firewall/templates/{id}/apply.

Name	Type	Required	Description
`vm`	`string`	yes	VM id.

AuditView

An audit record.

Name	Type	Required	Description
`action`	`string`	yes	Action.
`actor`	`string`	yes	Actor.
`afterHash`	`string` or `null`		After hash.
`at`	`string`	yes	Time.
`beforeHash`	`string` or `null`		Before hash.
`clientAddress`	`string`	yes	Client address.
`correlationId`	`string`	yes	Correlation id.
`details`	`object`	yes	Details.
`id`	`string`	yes	Id.
`outcome`	`string`	yes	`success`, `denied` or `error`.
`targetId`	`string` or `null`		Target.

AuthConfigView

GET /v1/auth/config: what the sign-in page needs before anyone is signed in.

Name	Type	Required	Description
`idleTimeoutSeconds`	`integer` (int64)	yes	Idle timeout of browser sessions in seconds.
`oidc`	`OidcConfigView`	yes	OIDC sign-in.

AuthLoginRequest

POST /v1/auth/login body.

Name	Type	Required	Description
`password`	`string`	yes	Password.
`username`	`string`	yes	Account name.

AuthMfaRequest

POST /v1/auth/mfa body: the challenge token and exactly one of code and recoveryCode.

Name	Type	Required	Description
`code`	`string` or `null`		Six-digit TOTP code.
`pendingToken`	`string`	yes	`pendingToken` from the login response (`mfaToken` is accepted as an alias).
`recoveryCode`	`string` or `null`		A recovery code.

AuthPasswordRequest

POST /v1/auth/password body.

Name	Type	Required	Description
`currentPassword`	`string`	yes	Current password.
`newPassword`	`string`	yes	New password (12..=256 characters, not common, not containing the username).

AuthResponse

Response of the browser login endpoints (/v1/auth/login, /mfa, /refresh, /password, /totp/confirm). Token responses also set the kyv_refresh and kyvernon_csrf cookies. Shape agreed with the UI (ui/app/src/auth/contract.ts).

Name	Type	Required	Description
`outcome`	`string`	yes	`session` (a session, possibly restricted to the password change, see `session.passwordRotationRequired`), `mfa_enrolment_required` (a session restricted to TOTP enrolment) or `mfa_required` (no session; answer with `pendingToken`).
`pendingToken`	`string` or `null`		For `mfa_required`: the single-use challenge token for `POST /v1/auth/mfa`.
`pendingTokenExpiresAt`	`string` or `null`		For `mfa_required`: expiry of the challenge (5 minutes).
`recoveryCodes`	array of `string` or `null`		Only from `POST /v1/auth/totp/confirm`: ten single-use recovery codes, shown once.
`session`	`AuthSessionTokens` or `null`
`stage`	`string` or `null`		What the session may do: `authenticated`, `password_change_required` or `mfa_enrolment_required`; absent for `mfa_required`.

AuthSessionTokens

A browser session in an [AuthResponse].

Name	Type	Required	Description
`accessExpiresAt`	`string`	yes	Expiry of this access token (RFC 3339; 15 min); refresh before it.
`csrfToken`	`string`	yes	The CSRF token (same value as the `kyvernon_csrf` cookie).
`expiresAt`	`string`	yes	Absolute expiry of the session (RFC 3339; 12 h after login).
`expiresIn`	`integer` (int64)	yes	Seconds until the access token expires.
`idleTimeoutSeconds`	`integer` (int64)	yes	Idle timeout of the session in seconds.
`mfaEnrolmentRequired`	`boolean`	yes	TOTP enrolment is required (after the password change, if that is pending too).
`passwordRotationRequired`	`boolean`	yes	Only the password change is allowed until it is done.
`sessionId`	`string`	yes	Session (token family) id.
`token`	`string`	yes	Bearer access token; keep it in memory only.
`tokenType`	`string`	yes	Always `Bearer`.
`user`	`UserView`	yes	The user.

AuthSessionView

GET /v1/auth/session response.

Name	Type	Required	Description
`accessTokenExpiresAt`	`string` or `null`		Expiry of the presented access token (browser sessions).
`createdAt`	`string`	yes	Creation time.
`idleTimeoutSeconds`	`integer` (int64)	yes	Idle timeout in seconds.
`mfaVerified`	`boolean`	yes	Second factor completed in this session.
`sessionExpiresAt`	`string`	yes	Absolute expiry.
`sessionId`	`string`	yes	Session id.
`stage`	`string`	yes	`authenticated`, `password_change_required` or `mfa_enrolment_required`.
`user`	`UserView`	yes	The user.

AvailableMetricView

One available (counter, instance) pair.

Name	Type	Required	Description
`counter`	`string`	yes	Counter name.
`counterId`	`integer` (int32)	yes	Counter id.
`instance`	`string`	yes	Instance (`""` = aggregate).

AvailableView

Counters with data for an entity.

Name	Type	Required	Description
`entity`	`string`	yes	Entity id.
`interval`	`integer` (int32)	yes	Sampling period.
`metrics`	array of `AvailableMetricView`	yes	Pairs.