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
| Name | Type | Required | Description |
|---|
folderId | string or null | | Datacenter folder to create it in (group-dN); default: the root folder. |
|---|
name | string | yes | Name, 1 to 80 characters, unique among the datacenters of the folder. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | ObjectView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the datacenter |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 412 | Failed precondition; the error body says which | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
since | query | integer (int64) | yes | Version to resume after (from a listing's version or the last response). |
|---|
timeout | query | integer (int64) or null | | Long-poll timeout in seconds (default 30, bounded by the server). |
|---|
kinds | query | string or null | | Comma-separated kinds to include (default all). |
|---|
limit | query | integer or null | | Maximum change sets per response (default 100). |
|---|
Responses
GET /v1/inventory/clusters/{id}
A cluster.
- CLI
kyvernon inventory cluster <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the cluster (domain-cN) |
|---|
Responses
GET /v1/inventory/datacenters/{id}
A datacenter.
- CLI
kyvernon inventory datacenter <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the datacenter |
|---|
Responses
GET /v1/inventory/datastores
Datastores, optionally scoped.
- CLI
kyvernon inventory datastores
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | string or null | | Container 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). |
|---|
limit | query | integer or null | | Maximum items (default 100, maximum 1000). |
|---|
after | query | string or null | | Resume after this id. |
|---|
consistency | query | string or null | | linearizable (default) or local. |
|---|
Responses
GET /v1/inventory/datastores/{id}
A datastore.
- CLI
kyvernon inventory datastore <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the datastore (datastore-N) |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the folder (group-N) |
|---|
Request body
application/json: MoveIntoFolderRequest
| Name | Type | Required | Description |
|---|
idempotencyKey | string or null | | Idempotency key. |
|---|
list | array of string | yes | Entities to move (vm-N, group-vN, …). Must be non-empty. |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
GET /v1/inventory/hosts
Hosts, optionally scoped.
- CLI
kyvernon inventory hosts
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | string or null | | Container 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). |
|---|
limit | query | integer or null | | Maximum items (default 100, maximum 1000). |
|---|
after | query | string or null | | Resume after this id. |
|---|
consistency | query | string or null | | linearizable (default) or local. |
|---|
Responses
GET /v1/inventory/hosts/{id}
A host.
- CLI
kyvernon inventory host <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the host (host-N) |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
kind | path | string | yes | Object kind of the inventory (for example VirtualMachine) |
|---|
parent | query | string or null | | Only direct children of this parent. |
|---|
namePrefix | query | string or null | | Name prefix. |
|---|
changedAfter | query | integer (int64) or null | | Only records changed after this version. |
|---|
limit | query | integer or null | | Maximum items. |
|---|
after | query | string or null | | Resume after id. |
|---|
consistency | query | string or null | | linearizable or local. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | Paged_ObjectView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
POST /v1/inventory/kinds/{kind}
Creates a record of kind under parentId.
- CLI
kyvernon inventory create <kind> --body <json>
Parameters
| Name | In | Type | Required | Description |
|---|
kind | path | string | yes | Object kind of the inventory (for example VirtualMachine) |
|---|
Request body
application/json: CreateObjectRequest
| Name | Type | Required | Description |
|---|
data | ObjectBody | yes | Body in the kind's schema. |
|---|
idempotencyKey | string or null | | Idempotency key; a repeat returns the same object. |
|---|
parentId | string or null | | Parent id (required for inventory entities). |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | ObjectView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
GET /v1/inventory/networks
Networks and distributed port groups, optionally scoped.
- CLI
kyvernon inventory networks
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | string or null | | Container 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). |
|---|
limit | query | integer or null | | Maximum items (default 100, maximum 1000). |
|---|
after | query | string or null | | Resume after this id. |
|---|
consistency | query | string or null | | linearizable (default) or local. |
|---|
Responses
GET /v1/inventory/networks/{id}
A network or distributed port group.
- CLI
kyvernon inventory network <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the network |
|---|
Responses
GET /v1/inventory/nodes/{id}/children
Direct children of a node (lazy tree loading).
- CLI
kyvernon inventory children <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Object id |
|---|
Responses
GET /v1/inventory/nodes/{id}/path
Ancestors of a node, root first, including the node (breadcrumb).
- CLI
kyvernon inventory path <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Object id |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the inventory object |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | ObjectView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the inventory object |
|---|
Request body
application/json: UpdateObjectRequest
| Name | Type | Required | Description |
|---|
data | ObjectBody | yes | New body, in the kind's schema. |
|---|
expectedVersion | integer (int64) | yes | Version the client read; the update fails with CONFLICT if it changed. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | ObjectView |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
DELETE /v1/inventory/objects/{id}
Deletes a record.
- CLI
kyvernon inventory delete <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the inventory object |
|---|
expectedVersion | query | integer (int64) or null | | Compare-and-set version. |
|---|
cascade | query | boolean or null | | Delete descendants too. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 412 | Failed precondition; the error body says which | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the inventory object |
|---|
Request body
application/json: RenameRequest
| Name | Type | Required | Description |
|---|
name | string | yes | The new name, 1 to 80 characters. |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
The tags attached to an object (System.View on the object).
- CLI
kyvernon inventory object-tags <id>
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the inventory object |
|---|
| Status | Description | Schema |
|---|
| 200 | OK | array of TagView |
|---|
| 404 | Not 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
GET /v1/inventory/search
Name search over tree nodes.
- CLI
kyvernon inventory search <q>
Parameters
| Name | In | Type | Required | Description |
|---|
q | query | string | yes | Case-insensitive substring of the name. |
|---|
limit | query | integer or null | | Maximum results (default 50). |
|---|
Responses
GET /v1/inventory/vms
Virtual machines, optionally scoped to a container.
- CLI
kyvernon inventory vms
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | string or null | | Container 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). |
|---|
limit | query | integer or null | | Maximum items (default 100, maximum 1000). |
|---|
after | query | string or null | | Resume after this id. |
|---|
consistency | query | string or null | | linearizable (default) or local. |
|---|
Responses
GET /v1/inventory/vms/{id}
A virtual machine.
- CLI
kyvernon inventory vm <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the resource group (resgroup-N) |
|---|
Request body
application/json: MoveIntoResourcePoolRequest
| Name | Type | Required | Description |
|---|
idempotencyKey | string or null | | Idempotency key. |
|---|
list | array of string | yes | Entities to move (vm-N, resgroup-N, …). Must be non-empty. |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not 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
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
| Name | Type | Required | Description |
|---|
associableKinds | array of string | | Object kinds the tags may be attached to; empty or absent: every inventory kind. |
|---|
cardinality | string or null | | single (default) or multiple. |
|---|
description | string | | Description. |
|---|
name | string | yes | Name, 1 to 80 characters, unique. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | TagCategoryView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
GET /v1/tag-categories/{id}
Reads a tag category.
- CLI
kyvernon inventory tag-categories get <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag category |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag category |
|---|
Request body
application/json: UpdateTagCategoryRequest
| Name | Type | Required | Description |
|---|
associableKinds | array of string or null | | The new list of associable kinds (a superset of the current one). |
|---|
cardinality | string or null | | multiple. |
|---|
description | string or null | | New description. |
|---|
expectedVersion | integer (int64) or null | | Version the client read; CONFLICT when the category changed since. |
|---|
name | string or null | | New name. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | TagCategoryView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag category |
|---|
expectedVersion | query | integer (int64) or null | | Version the client read; CONFLICT when the record changed since. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
Lists tags, optionally of one category (any authenticated user).
- CLI
kyvernon inventory tags list
| Name | In | Type | Required | Description |
|---|
categoryId | query | string or null | | Only tags of this category. |
|---|
| Status | Description | Schema |
|---|
| 200 | OK | array 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
| Name | Type | Required | Description |
|---|
categoryId | string | yes | Category id. |
|---|
description | string | | Description. |
|---|
name | string | yes | Name, 1 to 80 characters, unique within the category. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | TagView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
GET /v1/tags/{id}
Reads a tag.
- CLI
kyvernon inventory tags get <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | TagView |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
Request body
application/json: UpdateTagRequest
| Name | Type | Required | Description |
|---|
description | string or null | | New description. |
|---|
expectedVersion | integer (int64) or null | | Version the client read; CONFLICT when the tag changed since. |
|---|
name | string or null | | New name. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | TagView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
expectedVersion | query | integer (int64) or null | | Version the client read; CONFLICT when the record changed since. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
Request body
application/json: TagObjectsRequest
| Name | Type | Required | Description |
|---|
objectIds | array of string | yes | Inventory object ids (at most 1000). Every object is checked before any change is made: one refusal leaves all objects as they were. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | TagView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 412 | Failed precondition; the error body says which | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
Request body
application/json: TagObjectsRequest
| Name | Type | Required | Description |
|---|
objectIds | array of string | yes | Inventory object ids (at most 1000). Every object is checked before any change is made: one refusal leaves all objects as they were. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | TagView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag (tag-N) |
|---|
Responses
Version 0.1.