Documentation Reference REST API reference API: datastores Reference For: developers
API: datastores
Operations of the datastores tag of the native REST API.
Datastore files: folders, listing, streamed upload and download (also at /folder, the vSphere-compatible datastore endpoint)
GET /folder/{path}GET /folder/<path>?dcPath=&dsName=: downloads a file (vSphere datastore HTTP access; bearer, session cookie, or vmware_cgi_ticket; Range gives 206).
Parameters
Name In Type Required Description pathpath stringyes File path below the datastore root, each segment percent-encoded dcPathquery string or nullDatacenter name or inventory path (DC1, folder/DC1); may be omitted when the datastore name is unique. dsNamequery string or nullDatastore name.
Responses
Status Description Schema 200 OK 206 Partial content (the requested range) 401 Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required) ErrorBody404 Not found (or not visible to the caller) ErrorBody
PUT /folder/{path}PUT /folder/<path>?dcPath=&dsName=: uploads a file, streamed (replacing one that is not a VM disk, as vSphere does): 201 for a new file, 200 for a replaced one.
Parameters
Name In Type Required Description pathpath stringyes Datastore path of the file ([datastore] folder/file, URL-encoded) dcPathquery string or nullDatacenter name or inventory path (DC1, folder/DC1); may be omitted when the datastore name is unique. dsNamequery string or nullDatastore name.
Request body
application/octet-stream: array of integer (int32)
Responses
Status Description Schema 200 OK 201 Created 412 Failed precondition; the error body says which ErrorBody413 Payload too large (error.datastore_upload_too_large, args.limit) ErrorBody
DELETE /folder/{path}DELETE /folder/<path>?dcPath=&dsName=: deletes a file or folder.
Parameters
Name In Type Required Description pathpath stringyes Datastore path of the file ([datastore] folder/file, URL-encoded) dcPathquery string or nullDatacenter name or inventory path (DC1, folder/DC1); may be omitted when the datastore name is unique. dsNamequery string or nullDatastore name.
Responses
Status Description Schema 204 Done; no body 404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
DELETE /v1/datastores/{id}Removes a datastore from every host that mounts it and from the inventory (Datastore.Delete on the datastore and Host.Config.Storage on each host). The files stay on the storage. Refused while a virtual machine has a disk on it (error.datastore_file_in_use).
CLI kyvernon datastore remove <id>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N)
Responses
Status Description Schema 204 Done; no body 403 Permission denied; args.privilege names the missing privilege ErrorBody404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
GET /v1/datastores/{id}/filesLists a folder of a datastore.
CLI kyvernon datastore ls <id> [path]Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N) pathquery stringPath below the datastore root (iso/ubuntu.iso); empty for the root.
Responses
Status Description Schema 200 OK DatastoreListing404 Not found (or not visible to the caller) ErrorBody503 Temporarily unavailable (not the leader, or the service is off) ErrorBody
DELETE /v1/datastores/{id}/filesDeletes a file or a folder with its content. Disks of virtual machines, and folders holding them, are refused (FAILED_PRECONDITION, error.datastore_file_in_use).
CLI kyvernon datastore rm <id> <path>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N) pathquery stringPath below the datastore root (iso/ubuntu.iso); empty for the root.
Responses
Status Description Schema 204 Done; no body 404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
GET /v1/datastores/{id}/files/contentDownloads a file (streamed; Range: bytes=a-b gives 206).
CLI kyvernon datastore download <id> <path>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N) pathquery stringPath below the datastore root (iso/ubuntu.iso); empty for the root.
Responses
Status Description Schema 200 OK 206 Partial content (the requested range) 404 Not found (or not visible to the caller) ErrorBody416 Range not satisfiable ErrorBody
PUT /v1/datastores/{id}/files/contentUploads a file (streamed request body; written to a temporary file and renamed into place when complete).
CLI kyvernon datastore upload <id> <file>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N) pathquery stringyes Path of the new file below the datastore root. overwritequery booleanReplace an existing file (never a disk of a virtual machine).
Request body
application/octet-stream: array of integer (int32)
Responses
Status Description Schema 200 OK 201 Created 409 Conflict: the object exists, or expectedVersion is stale ErrorBody413 Payload too large (error.datastore_upload_too_large, args.limit) ErrorBody
POST /v1/datastores/{id}/files/copyCopies a file on a datastore (POST /v1/datastores/{id}/files/copy, SOAP CopyDatastoreFile_Task). Synchronous; same-host only. Privilege Datastore.FileManagement on source and destination.
CLI kyvernon datastore cp <id> <source> <destination>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N)
Request body
application/json: CopyMoveFileRequest
Name Type Required Description destinationDatastoreIdstring or nullDestination datastore (datastore-N). Defaults to the path datastore. destinationPathstringyes Destination path below the destination datastore root. overwritebooleanReplace an existing destination file. sourcePathstringyes Source path below the path datastore root.
Responses
Status Description Schema 201 Created 400 Invalid argument; the error body names the field ErrorBody404 Not found (or not visible to the caller) ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody412 Failed precondition; the error body says which ErrorBody
POST /v1/datastores/{id}/files/moveMoves or renames a file on a datastore (POST /v1/datastores/{id}/files/move, SOAP MoveDatastoreFile_Task). Synchronous; same-host only. Privilege Datastore.FileManagement on source and destination.
CLI kyvernon datastore mv <id> <source> <destination>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N)
Request body
application/json: CopyMoveFileRequest
Name Type Required Description destinationDatastoreIdstring or nullDestination datastore (datastore-N). Defaults to the path datastore. destinationPathstringyes Destination path below the destination datastore root. overwritebooleanReplace an existing destination file. sourcePathstringyes Source path below the path datastore root.
Responses
Status Description Schema 204 Done; no body 400 Invalid argument; the error body names the field ErrorBody404 Not found (or not visible to the caller) ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody412 Failed precondition; the error body says which ErrorBody
POST /v1/datastores/{id}/foldersCreates a folder on a datastore (ALREADY_EXISTS when the path exists).
CLI kyvernon datastore mkdir <id> <path>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N)
Request body
application/json: MakeFolderRequest
Name Type Required Description createParentsbooleanCreate missing parent folders too. pathstringyes Path of the new folder below the datastore root.
Responses
Status Description Schema 201 Created 409 Conflict: the object exists, or expectedVersion is stale ErrorBody
GET /v1/datastores/{id}/orphan-disksReports the disk images on a datastore that nothing references: no virtual machine, template or snapshot names them, and they are neither an overlay nor the backing image of a disk that is referenced, nor a content-library file. Report only: nothing is deleted. Images uploaded to make disks from are listed too; check before removing.
CLI kyvernon datastore orphans <id>Parameters
Name In Type Required Description idpath stringyes Id of the datastore (datastore-N) minAgeSecondsquery integer (int64) or nullLeave out files changed within this many seconds (default 300): a task may be making them right now.
Responses
Status Description Schema 200 OK OrphanDiskReport404 Not found (or not visible to the caller) ErrorBody503 Temporarily unavailable (not the leader, or the service is off) ErrorBody
POST /v1/datastores/{id}/refreshMeasures the datastore on a connected host that mounts it and stores its size and free space (System.Read on the datastore). The leader also does this every five minutes. Needs a host whose agent has the datastore-capacity capability (error.datastore_no_host otherwise).
CLI kyvernon datastore refresh <id>Parameters
Name In Type Required Description idpath stringyes Datastore id (datastore-N).
Responses
Status Description Schema 200 OK DatastoreCapacityView403 Permission denied; args.privilege names the missing privilege ErrorBody404 Not found (or not visible to the caller) ErrorBody503 Temporarily unavailable (not the leader, or the service is off) ErrorBody
POST /v1/hosts/{id}/datastores/{dsId}/mountMounts an existing NFS or iSCSI datastore on one more host, or again after an unmount (Host.Config.Storage on the host). A local datastore belongs to its host and cannot be mounted elsewhere (error.datastore.not_shareable).
CLI kyvernon host mount-datastore <id> <ds-id>Parameters
Name In Type Required Description idpath stringyes Id of the host (host-N) dsIdpath stringyes Id of the datastore on the host (datastore-N)
Responses
Status Description Schema 204 Done; no body 403 Permission denied; args.privilege names the missing privilege ErrorBody404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
POST /v1/hosts/{id}/datastores/{dsId}/unmountUnmounts a datastore on one host (Host.Config.Storage on the host). The datastore and its files stay; the host no longer offers it. Refused while a virtual machine placed on that host has a disk on it (error.datastore_file_in_use).
CLI kyvernon host unmount-datastore <id> <ds-id>Parameters
Name In Type Required Description idpath stringyes Id of the host (host-N) dsIdpath stringyes Id of the datastore on the host (datastore-N)
Responses
Status Description Schema 204 Done; no body 403 Permission denied; args.privilege names the missing privilege ErrorBody404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
Guides
Previous API: customization Next API: events Version 0.1.