Reference For: developers

API: inventory

Operations of the inventory tag of the native REST API.

Inventory tree, objects, change feed

POST /v1/datacenters

Creates a datacenter with its folders for virtual machines, hosts, networks and datastores (Datacenter.Create on the parent folder).

CLI
kyvernon inventory create-datacenter <name>

Request body

application/json: CreateDatacenterRequest

NameTypeRequiredDescription
folderIdstring or nullDatacenter folder to create it in (group-dN); default: the root folder.
namestringyesName, 1 to 80 characters, unique among the datacenters of the folder.

Responses

StatusDescriptionSchema
201CreatedObjectView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

DELETE /v1/datacenters/{id}

Deletes an empty datacenter and its folders (Datacenter.Delete on the datacenter). A datacenter that still holds clusters, hosts, virtual machines, networks or datastores is refused (error.datacenter.not_empty).

CLI
kyvernon inventory delete-datacenter <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the datacenter

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody
412Failed precondition; the error body says whichErrorBody

GET /v1/inventory/changes

Long-poll change feed. Returns immediately with retained history after since, otherwise waits up to timeout for new changes. resync: true means the client must re-list and resume from version.

CLI
kyvernon inventory changes --since <version>

Parameters

NameInTypeRequiredDescription
sincequeryinteger (int64)yesVersion to resume after (from a listing's version or the last response).
timeoutqueryinteger (int64) or nullLong-poll timeout in seconds (default 30, bounded by the server).
kindsquerystring or nullComma-separated kinds to include (default all).
limitqueryinteger or nullMaximum change sets per response (default 100).

Responses

StatusDescriptionSchema
200OKChangesResponse

GET /v1/inventory/clusters/{id}

A cluster.

CLI
kyvernon inventory cluster <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the cluster (domain-cN)

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/datacenters/{id}

A datacenter.

CLI
kyvernon inventory datacenter <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the datacenter

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/datastores

Datastores, optionally scoped.

CLI
kyvernon inventory datastores

Parameters

NameInTypeRequiredDescription
scopequerystring or nullContainer object id: datacenter, folder, cluster, host, resource pool, datastore or network. Items are returned when they live under the container or reference it (VMs on a host, datastore or network).
limitqueryinteger or nullMaximum items (default 100, maximum 1000).
afterquerystring or nullResume after this id.
consistencyquerystring or nulllinearizable (default) or local.

Responses

StatusDescriptionSchema
200OKPaged_ObjectView

GET /v1/inventory/datastores/{id}

A datastore.

CLI
kyvernon inventory datastore <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the datastore (datastore-N)

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

POST /v1/inventory/folders/{id}/move-into

Re-parents inventory entities under a folder (POST /v1/inventory/folders/{id}/move-into, SOAP Folder.MoveIntoFolder_Task). Returns a task; privilege Folder.Move on the destination folder.

CLI
kyvernon inventory move-into <id> --entity <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the folder (group-N)

Request body

application/json: MoveIntoFolderRequest

NameTypeRequiredDescription
idempotencyKeystring or nullIdempotency key.
listarray of stringyesEntities to move (vm-N, group-vN, …). Must be non-empty.

Responses

StatusDescriptionSchema
202Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait)TaskRef
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/hosts

Hosts, optionally scoped.

CLI
kyvernon inventory hosts

Parameters

NameInTypeRequiredDescription
scopequerystring or nullContainer object id: datacenter, folder, cluster, host, resource pool, datastore or network. Items are returned when they live under the container or reference it (VMs on a host, datastore or network).
limitqueryinteger or nullMaximum items (default 100, maximum 1000).
afterquerystring or nullResume after this id.
consistencyquerystring or nulllinearizable (default) or local.

Responses

StatusDescriptionSchema
200OKPaged_ObjectView

GET /v1/inventory/hosts/{id}

A host.

CLI
kyvernon inventory host <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the host (host-N)

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/kinds/{kind}

Records of one kind (virtual_machine, host, vm_folder, ...). Same privileges as GET /v1/inventory/objects/{id}: invisible records are left out, a kind the caller may not read is refused (403), and session is refused for everyone (400).

CLI
kyvernon inventory kind <kind>

Parameters

NameInTypeRequiredDescription
kindpathstringyesObject kind of the inventory (for example VirtualMachine)
parentquerystring or nullOnly direct children of this parent.
namePrefixquerystring or nullName prefix.
changedAfterqueryinteger (int64) or nullOnly records changed after this version.
limitqueryinteger or nullMaximum items.
afterquerystring or nullResume after id.
consistencyquerystring or nulllinearizable or local.

Responses

StatusDescriptionSchema
200OKPaged_ObjectView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody

POST /v1/inventory/kinds/{kind}

Creates a record of kind under parentId.

CLI
kyvernon inventory create <kind> --body <json>

Parameters

NameInTypeRequiredDescription
kindpathstringyesObject kind of the inventory (for example VirtualMachine)

Request body

application/json: CreateObjectRequest

NameTypeRequiredDescription
dataObjectBodyyesBody in the kind's schema.
idempotencyKeystring or nullIdempotency key; a repeat returns the same object.
parentIdstring or nullParent id (required for inventory entities).

Responses

StatusDescriptionSchema
201CreatedObjectView
400Invalid argument; the error body names the fieldErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

GET /v1/inventory/networks

Networks and distributed port groups, optionally scoped.

CLI
kyvernon inventory networks

Parameters

NameInTypeRequiredDescription
scopequerystring or nullContainer object id: datacenter, folder, cluster, host, resource pool, datastore or network. Items are returned when they live under the container or reference it (VMs on a host, datastore or network).
limitqueryinteger or nullMaximum items (default 100, maximum 1000).
afterquerystring or nullResume after this id.
consistencyquerystring or nulllinearizable (default) or local.

Responses

StatusDescriptionSchema
200OKPaged_ObjectView

GET /v1/inventory/networks/{id}

A network or distributed port group.

CLI
kyvernon inventory network <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the network

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/nodes/{id}/children

Direct children of a node (lazy tree loading).

CLI
kyvernon inventory children <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesObject id

Responses

StatusDescriptionSchema
200OKarray of InventoryNode
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/nodes/{id}/path

Ancestors of a node, root first, including the node (breadcrumb).

CLI
kyvernon inventory path <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesObject id

Responses

StatusDescriptionSchema
200OKarray of InventoryNode
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/objects/{id}

Any record by id. Inventory entities need System.View; other kinds need the privilege of their dedicated endpoint (users Kyvernon.Identity.ManageUsers, webhooks Kyvernon.Webhook.Manage, audit records Global.Diagnostics, the rest System.Read plus visibility of the entity they belong to). Session records are not served here. Secrets (password hashes, TOTP seeds, token hashes, signing and CHAP secrets) are never returned.

CLI
kyvernon inventory get <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the inventory object

Responses

StatusDescriptionSchema
200OKObjectView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
404Not found (or not visible to the caller)ErrorBody

PUT /v1/inventory/objects/{id}

Replaces a record's body (compare-and-set).

CLI
kyvernon inventory update <id> --expected-version <n> --body <json>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the inventory object

Request body

application/json: UpdateObjectRequest

NameTypeRequiredDescription
dataObjectBodyyesNew body, in the kind's schema.
expectedVersioninteger (int64)yesVersion the client read; the update fails with CONFLICT if it changed.

Responses

StatusDescriptionSchema
200OKObjectView
409Conflict: the object exists, or expectedVersion is staleErrorBody

DELETE /v1/inventory/objects/{id}

Deletes a record.

CLI
kyvernon inventory delete <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the inventory object
expectedVersionqueryinteger (int64) or nullCompare-and-set version.
cascadequeryboolean or nullDelete descendants too.

Responses

StatusDescriptionSchema
204Done; no body
412Failed precondition; the error body says whichErrorBody

POST /v1/inventory/objects/{id}/rename

Renames an inventory object: a datacenter (Datacenter.Rename), folder (Folder.Rename), cluster (Host.Inventory.EditCluster), host (Host.Config.Settings), resource group (Resource.EditPool), virtual machine (VirtualMachine.Config.Rename), datastore (Datastore.Rename) or network (Network.Config). Runs as a task (<Type>.rename).

CLI
kyvernon inventory rename <id> <name>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the inventory object

Request body

application/json: RenameRequest

NameTypeRequiredDescription
namestringyesThe new name, 1 to 80 characters.

Responses

StatusDescriptionSchema
202Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait)TaskRef
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/objects/{id}/tags

The tags attached to an object (System.View on the object).

CLI
kyvernon inventory object-tags <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the inventory object

Responses

StatusDescriptionSchema
200OKarray of TagView
404Not found (or not visible to the caller)ErrorBody

GET /v1/inventory/roots

Top-level tree nodes (datacenters) visible to the caller.

CLI
kyvernon inventory roots

Responses

StatusDescriptionSchema
200OKarray of InventoryNode

Name search over tree nodes.

CLI
kyvernon inventory search <q>

Parameters

NameInTypeRequiredDescription
qquerystringyesCase-insensitive substring of the name.
limitqueryinteger or nullMaximum results (default 50).

Responses

StatusDescriptionSchema
200OKarray of InventoryNode

GET /v1/inventory/vms

Virtual machines, optionally scoped to a container.

CLI
kyvernon inventory vms

Parameters

NameInTypeRequiredDescription
scopequerystring or nullContainer object id: datacenter, folder, cluster, host, resource pool, datastore or network. Items are returned when they live under the container or reference it (VMs on a host, datastore or network).
limitqueryinteger or nullMaximum items (default 100, maximum 1000).
afterquerystring or nullResume after this id.
consistencyquerystring or nulllinearizable (default) or local.

Responses

StatusDescriptionSchema
200OKPaged_ObjectView

GET /v1/inventory/vms/{id}

A virtual machine.

CLI
kyvernon inventory vm <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the virtual machine (vm-N)

Responses

StatusDescriptionSchema
200OKObjectView
404Not found (or not visible to the caller)ErrorBody

POST /v1/resource-pools/{id}/move-into

Moves VMs and/or child pools under a resource pool (POST /v1/resource-pools/{id}/move-into, SOAP MoveIntoResourcePool). Returns a task; privilege Resource.AssignVMToPool for VMs and Resource.MovePool for child pools on the destination.

CLI
kyvernon inventory move-into-pool <id> --entity <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the resource group (resgroup-N)

Request body

application/json: MoveIntoResourcePoolRequest

NameTypeRequiredDescription
idempotencyKeystring or nullIdempotency key.
listarray of stringyesEntities to move (vm-N, resgroup-N, …). Must be non-empty.

Responses

StatusDescriptionSchema
202Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait)TaskRef
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody

GET /v1/tag-categories

Lists tag categories (any authenticated user).

CLI
kyvernon inventory tag-categories list

Responses

StatusDescriptionSchema
200OKarray of TagCategoryView

POST /v1/tag-categories

Creates a tag category (InventoryService.Tagging.CreateCategory on the root folder).

CLI
kyvernon inventory tag-categories create <name>

Request body

application/json: CreateTagCategoryRequest

NameTypeRequiredDescription
associableKindsarray of stringObject kinds the tags may be attached to; empty or absent: every inventory kind.
cardinalitystring or nullsingle (default) or multiple.
descriptionstringDescription.
namestringyesName, 1 to 80 characters, unique.

Responses

StatusDescriptionSchema
201CreatedTagCategoryView
400Invalid argument; the error body names the fieldErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

GET /v1/tag-categories/{id}

Reads a tag category.

CLI
kyvernon inventory tag-categories get <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag category

Responses

StatusDescriptionSchema
200OKTagCategoryView
404Not found (or not visible to the caller)ErrorBody

PUT /v1/tag-categories/{id}

Changes a tag category (InventoryService.Tagging.EditCategory on the root folder).

CLI
kyvernon inventory tag-categories update <id> --name <name>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag category

Request body

application/json: UpdateTagCategoryRequest

NameTypeRequiredDescription
associableKindsarray of string or nullThe new list of associable kinds (a superset of the current one).
cardinalitystring or nullmultiple.
descriptionstring or nullNew description.
expectedVersioninteger (int64) or nullVersion the client read; CONFLICT when the category changed since.
namestring or nullNew name.

Responses

StatusDescriptionSchema
200OKTagCategoryView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

DELETE /v1/tag-categories/{id}

Deletes a tag category with its tags (InventoryService.Tagging.DeleteCategory on the root folder). The tags are detached from every object.

CLI
kyvernon inventory tag-categories delete <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag category
expectedVersionqueryinteger (int64) or nullVersion the client read; CONFLICT when the record changed since.

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

GET /v1/tags

Lists tags, optionally of one category (any authenticated user).

CLI
kyvernon inventory tags list

Parameters

NameInTypeRequiredDescription
categoryIdquerystring or nullOnly tags of this category.

Responses

StatusDescriptionSchema
200OKarray of TagView

POST /v1/tags

Creates a tag (InventoryService.Tagging.CreateTag on the root folder).

CLI
kyvernon inventory tags create <category> <name>

Request body

application/json: CreateTagRequest

NameTypeRequiredDescription
categoryIdstringyesCategory id.
descriptionstringDescription.
namestringyesName, 1 to 80 characters, unique within the category.

Responses

StatusDescriptionSchema
201CreatedTagView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

GET /v1/tags/{id}

Reads a tag.

CLI
kyvernon inventory tags get <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)

Responses

StatusDescriptionSchema
200OKTagView
404Not found (or not visible to the caller)ErrorBody

PUT /v1/tags/{id}

Changes a tag (InventoryService.Tagging.EditTag on the root folder).

CLI
kyvernon inventory tags update <id> --name <name>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)

Request body

application/json: UpdateTagRequest

NameTypeRequiredDescription
descriptionstring or nullNew description.
expectedVersioninteger (int64) or nullVersion the client read; CONFLICT when the tag changed since.
namestring or nullNew name.

Responses

StatusDescriptionSchema
200OKTagView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

DELETE /v1/tags/{id}

Deletes a tag (InventoryService.Tagging.DeleteTag on the root folder). It is detached from every object.

CLI
kyvernon inventory tags delete <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)
expectedVersionqueryinteger (int64) or nullVersion the client read; CONFLICT when the record changed since.

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

POST /v1/tags/{id}/attach

Attaches a tag to objects (InventoryService.Tagging.AttachTag on each object). Objects that already carry the tag are left as they are.

CLI
kyvernon inventory tags attach <id> <object>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)

Request body

application/json: TagObjectsRequest

NameTypeRequiredDescription
objectIdsarray of stringyesInventory object ids (at most 1000). Every object is checked before any change is made: one refusal leaves all objects as they were.

Responses

StatusDescriptionSchema
200OKTagView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
404Not found (or not visible to the caller)ErrorBody
412Failed precondition; the error body says whichErrorBody

POST /v1/tags/{id}/detach

Detaches a tag from objects (InventoryService.Tagging.AttachTag on each object). Objects that do not carry the tag are left as they are.

CLI
kyvernon inventory tags detach <id> <object>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)

Request body

application/json: TagObjectsRequest

NameTypeRequiredDescription
objectIdsarray of stringyesInventory object ids (at most 1000). Every object is checked before any change is made: one refusal leaves all objects as they were.

Responses

StatusDescriptionSchema
200OKTagView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
404Not found (or not visible to the caller)ErrorBody

GET /v1/tags/{id}/objects

The objects a tag is attached to that the caller can see.

CLI
kyvernon inventory tags objects <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the tag (tag-N)

Responses

StatusDescriptionSchema
200OKarray of TaggedObjectView
404Not found (or not visible to the caller)ErrorBody

Version 0.1.