files

« Previous section Next section »

UCloud Developer Guide / Orchestration of Resources / Storage / Files

Files

Files in UCloud is a resource for storing, retrieving and organizing data in UCloud.

Rationale

📝 NOTE: This API follows the standard Resources API. We recommend that you have already read and understood the concepts described here.

---

The file-system of UCloud provide researchers with a way of storing large data-sets efficiently and securely. The file-system is one of UCloud's core features and almost all other features, either directly or indirectly, interact with it. For example:

• All interactions in UCloud (including files) are automatically audited

• UCloud allows compute Jobs to consume UCloud files. Either through containerized workloads or virtual machines.

• Authorization and project management

• Powerful file metadata system for data management

A file in UCloud (UFile) closely follows the concept of a computer file you might already be familiar with. The functionality of a file is mostly determined by its type. The two most important types are the DIRECTORY and FILE types. A DIRECTORY is a container of UFiles. A directory can itself contain more directories, which leads to a natural tree-like structure. FILEs, also referred to as a regular files, are data records which each contain a series of bytes.

---

📝 Provider Note: This is the API exposed to end-users. See the table below for other relevant APIs.

End-User	Provider (Ingoing)	Control (Outgoing)
Files	FilesProvider	FilesControl

---

Table of Contents

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Renaming a file

Frequency of use	Common
Trigger	User-initiated action, typically though the user-interface
Pre-conditions	A file present at /123/my/file The user has EDIT permissions on the file
Post-conditions	The file is moved to /123/my/new_file
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.move.call(
    bulkRequestOf(FilesMoveRequestItem(
        conflictPolicy = WriteConflictPolicy.REJECT, 
        newId = "/123/my/new_file", 
        oldId = "/123/my/file", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(LongRunningTask.Complete()), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/move" -d '{
    "items": [
        {
            "oldId": "/123/my/file",
            "newId": "/123/my/new_file",
            "conflictPolicy": "REJECT"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "type": "complete"
#         }
#     ]
# }

Communication Flow: Visual

Example: Copying a file to itself

Frequency of use	Common
Trigger	User-initiated action, typically through the user-interface
Pre-conditions	A file present at /123/my/file The user has EDIT permissions on the file The provider supports RENAME for conflict policies
Post-conditions	A new file present at '/123/my/file (1)'
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.copy.call(
    bulkRequestOf(FilesCopyRequestItem(
        conflictPolicy = WriteConflictPolicy.RENAME, 
        newId = "/123/my/file", 
        oldId = "/123/my/file", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(LongRunningTask.Complete()), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/copy" -d '{
    "items": [
        {
            "oldId": "/123/my/file",
            "newId": "/123/my/file",
            "conflictPolicy": "RENAME"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "type": "complete"
#         }
#     ]
# }

Communication Flow: Visual

Example: Uploading a file

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A folder at '/123/folder' The user has EDIT permissions on the file The provider supports the CHUNKED protocol
Post-conditions	A new file present at '/123/folder/file'
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.createUpload.call(
    bulkRequestOf(FilesCreateUploadRequestItem(
        conflictPolicy = WriteConflictPolicy.REJECT, 
        id = "/123/folder", 
        supportedProtocols = listOf(UploadProtocol.CHUNKED), 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FilesCreateUploadResponseItem(
        endpoint = "https://provider.example.com/ucloud/example-provider/chunked", 
        protocol = UploadProtocol.CHUNKED, 
        token = "f1460d47e583653f7723204e5ff3f50bad91a658", 
    )), 
)
*/

/* The user can now proceed to upload using the chunked protocol at the provided endpoint */

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/upload" -d '{
    "items": [
        {
            "id": "/123/folder",
            "supportedProtocols": [
                "CHUNKED"
            ],
            "conflictPolicy": "REJECT"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "endpoint": "https://provider.example.com/ucloud/example-provider/chunked",
#             "protocol": "CHUNKED",
#             "token": "f1460d47e583653f7723204e5ff3f50bad91a658"
#         }
#     ]
# }

# The user can now proceed to upload using the chunked protocol at the provided endpoint

Communication Flow: Visual

Example: Downloading a file

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A file at '/123/folder/file The user has READ permissions on the file
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.createDownload.call(
    bulkRequestOf(FilesCreateDownloadRequestItem(
        id = "/123/folder/file", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FilesCreateDownloadResponseItem(
        endpoint = "https://provider.example.com/ucloud/example-provider/download?token=d293435e94734c91394f17bb56268d3161c7f069", 
    )), 
)
*/

/* The user can now download the file through normal HTTP(s) GET at the provided endpoint */

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/download" -d '{
    "items": [
        {
            "id": "/123/folder/file"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "endpoint": "https://provider.example.com/ucloud/example-provider/download?token=d293435e94734c91394f17bb56268d3161c7f069"
#         }
#     ]
# }

# The user can now download the file through normal HTTP(s) GET at the provided endpoint

Communication Flow: Visual

Example: Creating a folder

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A folder at '/123/folder The user has EDIT permissions on the file
Post-conditions	A new file exists at '/123/folder/a
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.createFolder.call(
    bulkRequestOf(FilesCreateFolderRequestItem(
        conflictPolicy = WriteConflictPolicy.REJECT, 
        id = "/123/folder/a", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(LongRunningTask.Complete()), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/folder" -d '{
    "items": [
        {
            "id": "/123/folder/a",
            "conflictPolicy": "REJECT"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "type": "complete"
#         }
#     ]
# }

Communication Flow: Visual

Example: Moving multiple files to trash

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A folder at '/123/folder' A file at '/123/file' The user has EDIT permissions for all files involved
Post-conditions	The folder and all children are moved to the provider's trash folder The file is moved to the provider's trash folder
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.trash.call(
    bulkRequestOf(FindByPath(
        id = "/123/folder", 
    ), FindByPath(
        id = "/123/file", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(LongRunningTask.Complete(), LongRunningTask.Complete()), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/trash" -d '{
    "items": [
        {
            "id": "/123/folder"
        },
        {
            "id": "/123/file"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "type": "complete"
#         },
#         {
#             "type": "complete"
#         }
#     ]
# }

Communication Flow: Visual

Example: Emptying trash folder

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A trash folder located at /home/trash The trash folder contains two files and a folder
Post-conditions	The folder and all children are removed from the trash folder The files is removed from the trash folder
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.trash.call(
    bulkRequestOf(FindByPath(
        id = "/home/trash", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(LongRunningTask.Complete()), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files/trash" -d '{
    "items": [
        {
            "id": "/home/trash"
        }
    ]
}'


# {
#     "responses": [
#         {
#             "type": "complete"
#         }
#     ]
# }

Communication Flow: Visual

Example: Browsing the contents of a folder

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A folder at '/123/folder The user has READ permissions on the file
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.browse.call(
    ResourceBrowseRequest(
        consistency = null, 
        flags = UFileIncludeFlags(
            allowUnsupportedInclude = null, 
            filterByFileExtension = null, 
            filterCreatedAfter = null, 
            filterCreatedBefore = null, 
            filterCreatedBy = null, 
            filterHiddenFiles = false, 
            filterIds = null, 
            filterProductCategory = null, 
            filterProductId = null, 
            filterProvider = null, 
            filterProviderIds = null, 
            hideProductCategory = null, 
            hideProductId = null, 
            hideProvider = null, 
            includeMetadata = null, 
            includeOthers = false, 
            includePermissions = null, 
            includeProduct = false, 
            includeSizes = null, 
            includeSupport = false, 
            includeTimestamps = true, 
            includeUnixInfo = null, 
            includeUpdates = false, 
            path = null, 
        ), 
        itemsPerPage = null, 
        itemsToSkip = null, 
        next = null, 
        sortBy = null, 
        sortDirection = null, 
    ),
    user
).orThrow()

/*
PageV2(
    items = listOf(UFile(
        createdAt = 1632903417165, 
        id = "/123/folder/file.txt", 
        owner = ResourceOwner(
            createdBy = "user", 
            project = "f63919cd-60d3-45d3-926b-0246dcc697fd", 
        ), 
        permissions = null, 
        specification = UFileSpecification(
            collection = "123", 
            product = ProductReference(
                category = "u1-cephfs", 
                id = "u1-cephfs", 
                provider = "ucloud", 
            ), 
        ), 
        status = UFileStatus(
            accessedAt = null, 
            icon = null, 
            metadata = null, 
            modifiedAt = 1632903417165, 
            resolvedProduct = null, 
            resolvedSupport = null, 
            sizeInBytes = null, 
            sizeIncludingChildrenInBytes = null, 
            type = FileType.FILE, 
            unixGroup = null, 
            unixMode = null, 
            unixOwner = null, 
        ), 
        updates = emptyList(), 
        providerGeneratedId = "/123/folder/file.txt", 
    )), 
    itemsPerPage = 50, 
    next = null, 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/files/browse?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&includeTimestamps=true&filterHiddenFiles=false" 

# {
#     "itemsPerPage": 50,
#     "items": [
#         {
#             "id": "/123/folder/file.txt",
#             "specification": {
#                 "collection": "123",
#                 "product": {
#                     "id": "u1-cephfs",
#                     "category": "u1-cephfs",
#                     "provider": "ucloud"
#                 }
#             },
#             "createdAt": 1632903417165,
#             "status": {
#                 "type": "FILE",
#                 "icon": null,
#                 "sizeInBytes": null,
#                 "sizeIncludingChildrenInBytes": null,
#                 "modifiedAt": 1632903417165,
#                 "accessedAt": null,
#                 "unixMode": null,
#                 "unixOwner": null,
#                 "unixGroup": null,
#                 "metadata": null,
#                 "resolvedSupport": null,
#                 "resolvedProduct": null
#             },
#             "owner": {
#                 "createdBy": "user",
#                 "project": "f63919cd-60d3-45d3-926b-0246dcc697fd"
#             },
#             "permissions": null,
#             "updates": [
#             ]
#         }
#     ],
#     "next": null
# }

Communication Flow: Visual

Example: Retrieving a single file

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A file at '/123/folder The user has READ permissions on the file
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.retrieve.call(
    ResourceRetrieveRequest(
        flags = UFileIncludeFlags(
            allowUnsupportedInclude = null, 
            filterByFileExtension = null, 
            filterCreatedAfter = null, 
            filterCreatedBefore = null, 
            filterCreatedBy = null, 
            filterHiddenFiles = false, 
            filterIds = null, 
            filterProductCategory = null, 
            filterProductId = null, 
            filterProvider = null, 
            filterProviderIds = null, 
            hideProductCategory = null, 
            hideProductId = null, 
            hideProvider = null, 
            includeMetadata = null, 
            includeOthers = false, 
            includePermissions = null, 
            includeProduct = false, 
            includeSizes = null, 
            includeSupport = false, 
            includeTimestamps = true, 
            includeUnixInfo = null, 
            includeUpdates = false, 
            path = null, 
        ), 
        id = "/123/folder", 
    ),
    user
).orThrow()

/*
UFile(
    createdAt = 1632903417165, 
    id = "/123/folder", 
    owner = ResourceOwner(
        createdBy = "user", 
        project = "f63919cd-60d3-45d3-926b-0246dcc697fd", 
    ), 
    permissions = null, 
    specification = UFileSpecification(
        collection = "123", 
        product = ProductReference(
            category = "u1-cephfs", 
            id = "u1-cephfs", 
            provider = "ucloud", 
        ), 
    ), 
    status = UFileStatus(
        accessedAt = null, 
        icon = null, 
        metadata = null, 
        modifiedAt = 1632903417165, 
        resolvedProduct = null, 
        resolvedSupport = null, 
        sizeInBytes = null, 
        sizeIncludingChildrenInBytes = null, 
        type = FileType.DIRECTORY, 
        unixGroup = null, 
        unixMode = null, 
        unixOwner = null, 
    ), 
    updates = emptyList(), 
    providerGeneratedId = "/123/folder", 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/files/retrieve?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&includeTimestamps=true&filterHiddenFiles=false&id=/123/folder" 

# {
#     "id": "/123/folder",
#     "specification": {
#         "collection": "123",
#         "product": {
#             "id": "u1-cephfs",
#             "category": "u1-cephfs",
#             "provider": "ucloud"
#         }
#     },
#     "createdAt": 1632903417165,
#     "status": {
#         "type": "DIRECTORY",
#         "icon": null,
#         "sizeInBytes": null,
#         "sizeIncludingChildrenInBytes": null,
#         "modifiedAt": 1632903417165,
#         "accessedAt": null,
#         "unixMode": null,
#         "unixOwner": null,
#         "unixGroup": null,
#         "metadata": null,
#         "resolvedSupport": null,
#         "resolvedProduct": null
#     },
#     "owner": {
#         "createdBy": "user",
#         "project": "f63919cd-60d3-45d3-926b-0246dcc697fd"
#     },
#     "permissions": null,
#     "updates": [
#     ]
# }

Communication Flow: Visual

Example: Deleting a file permanently

Frequency of use	Common
Trigger	User initiated
Pre-conditions	A file at '/123/folder The user has EDIT permissions on the file
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.delete.call(
    bulkRequestOf(FindByStringId(
        id = "/123/folder", 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(Unit), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XDELETE -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/files" -d '{
    "items": [
        {
            "id": "/123/folder"
        }
    ]
}'


# {
#     "responses": [
#         {
#         }
#     ]
# }

Communication Flow: Visual

Example: Retrieving a list of products supported by accessible providers

Frequency of use	Common
Trigger	Typically triggered by a client to determine which operations are supported
Pre-conditions	The user has access to the 'ucloud' provider
Actors	An authenticated user (user)

Communication Flow: Kotlin

Files.retrieveProducts.call(
    Unit,
    user
).orThrow()

/*
SupportByProvider(
    productsByProvider = mapOf("ucloud" to listOf(ResolvedSupport(
        product = Product.Storage(
            allowAllocationRequestsFrom = AllocationRequestsGroup.ALL, 
            category = ProductCategoryId(
                id = "u1-cephfs", 
                name = "u1-cephfs", 
                provider = "ucloud", 
            ), 
            chargeType = ChargeType.DIFFERENTIAL_QUOTA, 
            description = "Storage provided by UCloud", 
            freeToUse = false, 
            hiddenInGrantApplications = false, 
            name = "u1-cephfs", 
            pricePerUnit = 1, 
            priority = 0, 
            productType = ProductType.STORAGE, 
            unitOfPrice = ProductPriceUnit.PER_UNIT, 
            version = 1, 
            balance = null, 
            id = "u1-cephfs", 
            maxUsableBalance = null, 
        ), 
        support = FSSupport(
            collection = FSCollectionSupport(
                aclModifiable = false, 
                usersCanCreate = true, 
                usersCanDelete = true, 
                usersCanRename = true, 
            ), 
            files = FSFileSupport(
                aclModifiable = false, 
                isReadOnly = false, 
                searchSupported = true, 
                sharesSupported = true, 
                streamingSearchSupported = false, 
                trashSupported = true, 
            ), 
            maintenance = null, 
            product = ProductReference(
                category = "u1-cephfs", 
                id = "u1-cephfs", 
                provider = "ucloud", 
            ), 
            stats = FSProductStatsSupport(
                accessedAt = false, 
                createdAt = true, 
                modifiedAt = true, 
                sizeInBytes = true, 
                sizeIncludingChildrenInBytes = true, 
                unixGroup = true, 
                unixOwner = true, 
                unixPermissions = true, 
            ), 
        ), 
    ))), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/files/retrieveProducts" 

# {
#     "productsByProvider": {
#         "ucloud": [
#             {
#                 "product": {
#                     "balance": null,
#                     "maxUsableBalance": null,
#                     "name": "u1-cephfs",
#                     "pricePerUnit": 1,
#                     "category": {
#                         "name": "u1-cephfs",
#                         "provider": "ucloud"
#                     },
#                     "description": "Storage provided by UCloud",
#                     "priority": 0,
#                     "version": 1,
#                     "freeToUse": false,
#                     "allowAllocationRequestsFrom": "ALL",
#                     "unitOfPrice": "PER_UNIT",
#                     "chargeType": "DIFFERENTIAL_QUOTA",
#                     "hiddenInGrantApplications": false,
#                     "productType": "STORAGE"
#                 },
#                 "support": {
#                     "product": {
#                         "id": "u1-cephfs",
#                         "category": "u1-cephfs",
#                         "provider": "ucloud"
#                     },
#                     "stats": {
#                         "sizeInBytes": true,
#                         "sizeIncludingChildrenInBytes": true,
#                         "modifiedAt": true,
#                         "createdAt": true,
#                         "accessedAt": false,
#                         "unixPermissions": true,
#                         "unixOwner": true,
#                         "unixGroup": true
#                     },
#                     "collection": {
#                         "aclModifiable": false,
#                         "usersCanCreate": true,
#                         "usersCanDelete": true,
#                         "usersCanRename": true
#                     },
#                     "files": {
#                         "aclModifiable": false,
#                         "trashSupported": true,
#                         "isReadOnly": false,
#                         "searchSupported": true,
#                         "streamingSearchSupported": false,
#                         "sharesSupported": true
#                     },
#                     "maintenance": null
#                 }
#             }
#         ]
#     }
# }

Communication Flow: Visual

Remote Procedure Calls

browse

Browses the contents of a directory.

Request	Response	Error
ResourceBrowseRequest<UFileIncludeFlags>	PageV2<UFile>	CommonErrorMessage

The results will be returned using the standard pagination API of UCloud. Consistency is slightly relaxed for this endpoint as it is typically hard to enforce for filesystems. Provider's are heavily encouraged to try and find all files on the first request and return information about them in subsequent requests. For example, a client might list all file names in the initial request and use this list for all subsequent requests and retrieve additional information about the files. If the files no longer exist then the provider should simply not include these results.

retrieve

Retrieves information about a single file.

Request	Response	Error
ResourceRetrieveRequest<UFileIncludeFlags>	UFile	CommonErrorMessage

This file can be of any type. Clients can request additional information about the file using the include* flags of the request. Note that not all providers support all information. Clients can query this information using files.collections.browse or files.collections.retrieve with the includeSupport flag.

retrieveProducts

Retrieve product support for all accessible providers

Request	Response	Error
Unit	SupportByProvider<Product.Storage, FSSupport>	CommonErrorMessage

This endpoint will determine all providers that which the authenticated user has access to, in the current workspace. A user has access to a product, and thus a provider, if the product is either free or if the user has been granted credits to use the product.

See also:

• Product

• Grants

search

Searches the catalog of available resources

Request	Response	Error
ResourceSearchRequest<UFileIncludeFlags>	PageV2<UFile>	CommonErrorMessage

streamingSearch

Searches through the files of a user in all accessible files

Request	Response	Error
FilesStreamingSearchRequest	FilesStreamingSearchResult	CommonErrorMessage

This endpoint uses a specialized API for returning search results in a streaming fashion. In all other ways, this endpoint is identical to the normal search API.

This endpoint can be used instead of the normal search API as it will contact providers using the non-streaming version if they do not support it. In such a case, the core will retrieve multiple pages in order to stream in more content.

Clients should expect that this endpoint stops returning results after a given timeout. After which, it is no longer possible to request additional results.

copy

Copies a file from one path to another

Request	Response	Error
BulkRequest<FilesCopyRequestItem>	BulkResponse<LongRunningTask>	CommonErrorMessage

The file can be of any type. If a directory is chosen then this will recursively copy all of its children. This request might fail half-way through. This can potentially lead to a situation where a partial file is left on the file-system. It is left to the user to clean up this file.

This operation handles conflicts depending on the supplied WriteConflictPolicy.

This is a long running task. As a result, this operation might respond with a status code which indicate that it will continue in the background. Progress of this job can be followed using the task API.

UCloud applied metadata will not be copied to the new file. File-system metadata (e.g. extended-attributes) may be moved, however this is provider dependant.

Errors:

Status Code	Description
400 Bad Request	The operation couldn't be completed because of the write conflict policy
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation

Examples:

Example
Example of duplicating a file

createDownload

Creates a download session between the user and the provider

Request	Response	Error
BulkRequest<FilesCreateDownloadRequestItem>	BulkResponse<FilesCreateDownloadResponseItem>	CommonErrorMessage

The returned endpoint will respond with a download to the user.

Errors:

Status Code	Description
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation

Examples:

Example
Downloading a file

createFolder

Creates one or more folders

Request	Response	Error
BulkRequest<FilesCreateFolderRequestItem>	BulkResponse<LongRunningTask>	CommonErrorMessage

This folder will automatically create parent directories if needed. This request may fail half-way through and leave the file-system in an inconsistent state. It is up to the user to clean this up.

Errors:

Status Code	Description
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation

Examples:

Example
Creating a folder

createUpload

Creates an upload session between the user and the provider

Request	Response	Error
BulkRequest<FilesCreateUploadRequestItem>	BulkResponse<FilesCreateUploadResponseItem>	CommonErrorMessage

The returned endpoint will accept an upload from the user which will create a file at a location specified in this request.

Errors:

Status Code	Description
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation

Examples:

Example
Uploading a file with the chunked protocol

delete

Permanently deletes one or more files

Request	Response	Error
BulkRequest<FindByStringId>	BulkResponse<Unit>	CommonErrorMessage

This call will recursively delete files if needed. It is possible that a provider might fail to completely delete the entire sub-tree. This can, for example, happen because of a crash or because the file-system is unable to delete a given file. This will lead the file-system in an inconsistent state. It is not guaranteed that the provider will be able to detect this error scenario. A client of the API can check if the file has been deleted by calling retrieve on the file.

emptyTrash

Permanently deletes all files from the selected trash folder thereby emptying it

Request	Response	Error
BulkRequest<FindByPath>	BulkResponse<LongRunningTask>	CommonErrorMessage

This operation acts as a permanent delete for users. Users will NOT be able to restore the file later, if needed.

Not all providers supports this endpoint. You can query files.collections.browse or files.collections.retrieve with the includeSupport flag.

This is a long running task. As a result, this operation might respond with a status code which indicate that it will continue in the background. Progress of this job can be followed using the task API.

Errors:

Status Code	Description
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation
400 Bad Request	This operation is not supported by the provider

Examples:

Example
Moving files to trash

init

Request (potential) initialization of resources

Request	Response	Error
Unit	Unit	CommonErrorMessage

This request is sent by the client, if the client believes that initialization of resources might be needed. NOTE: This request might be sent even if initialization has already taken place. UCloud/Core does not check if initialization has already taken place, it simply validates the request.

move

Move a file from one path to another

Request	Response	Error
BulkRequest<FilesMoveRequestItem>	BulkResponse<LongRunningTask>	CommonErrorMessage

The file can be of any type. This request is also used for 'renames' of a file. This is simply considered a move within a single directory. This operation handles conflicts depending on the supplied WriteConflictPolicy.

This is a long running task. As a result, this operation might respond with a status code which indicate that it will continue in the background. Progress of this job can be followed using the task API.

Errors:

Status Code	Description
400 Bad Request	The operation couldn't be completed because of the write conflict policy
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation

Examples:

Example
Example of using move to rename a file

trash

Moves a file to the trash

Request	Response	Error
BulkRequest<FindByPath>	BulkResponse<LongRunningTask>	CommonErrorMessage

This operation acts as a non-permanent delete for users. Users will be able to restore the file from trash later, if needed. It is up to the provider to determine if the trash should be automatically deleted and where this trash should be stored.

Not all providers supports this endpoint. You can query files.collections.browse or files.collections.retrieve with the includeSupport flag.

This is a long running task. As a result, this operation might respond with a status code which indicate that it will continue in the background. Progress of this job can be followed using the task API.

Errors:

Status Code	Description
404 Not Found	Either the oldPath or newPath exists or you lack permissions
403 Forbidden	You lack permissions to perform this operation
400 Bad Request	This operation is not supported by the provider

Examples:

Example
Moving files to trash

updateAcl

Updates the ACL of a single file.

Request	Response	Error
BulkRequest<UpdatedAcl>	BulkResponse<Unit>	CommonErrorMessage

---

⚠️ WARNING: No providers currently support this API. Instead use the files.collections.updateAcl endpoint.

---

Data Models

UFile

A UFile is a resource for storing, retrieving and organizing data in UCloud

data class UFile(
    val id: String,
    val specification: UFileSpecification,
    val createdAt: Long,
    val status: UFileStatus,
    val owner: ResourceOwner,
    val permissions: ResourcePermissions?,
    val updates: List<UFileUpdate>,
    val providerGeneratedId: String?,
)

A file in UCloud (UFile) closely follows the concept of a computer file you might already be familiar with. The functionality of a file is mostly determined by its type. The two most important types are the DIRECTORY and FILE types. A DIRECTORY is a container of UFiles. A directory can itself contain more directories, which leads to a natural tree-like structure. FILEs, also referred to as a regular files, are data records which each contain a series of bytes.

All files in UCloud have a name associated with them. This name uniquely identifies them within their directory. All files in UCloud belong to exactly one directory.

File operations must be able to reference the files on which they operate. In UCloud, these references are made through the id property, also known as a path. Paths use the tree-like structure of files to reference a file, it does so by declaring which directories to go through, starting at the top, to reach the file we are referencing. This information is serialized as a textual string, where each step of the path is separated by forward-slash / (U+002F). The path must start with a single forward-slash, which signifies the root of the file tree. UCloud never users 'relative' file paths, which some systems use.

All files in UCloud additionally have metadata associated with them. For this we differentiate between system-level metadata and user-defined metadata.

We have just covered two examples of system-level metadata, the id (path) and type. UCloud additionally supports metadata such as general stats about the files, such as file sizes. All files have a set of permissions associated with them, providers may optionally expose this information to UCloud and the users.

User-defined metadata describe the contents of a file. All metadata is described by a template (FileMetadataTemplate), this template defines a document structure for the metadata. User-defined metadata can be used for a variety of purposes, such as: Datacite metadata, sensitivity levels, and other field specific metadata formats.

Properties

---

UFileStatus

General system-level stats about a file

data class UFileStatus(
    val type: FileType?,
    val icon: FileIconHint?,
    val sizeInBytes: Long?,
    val sizeIncludingChildrenInBytes: Long?,
    val modifiedAt: Long?,
    val accessedAt: Long?,
    val unixMode: Int?,
    val unixOwner: Int?,
    val unixGroup: Int?,
    val metadata: FileMetadataHistory?,
    val resolvedSupport: ResolvedSupport<Product.Storage, FSSupport>?,
    val resolvedProduct: Product.Storage?,
)

Properties

---

FileIconHint

A hint to clients about which icon should be used in user-interfaces when representing a UFile

enum class FileIconHint {
    DIRECTORY_STAR,
    DIRECTORY_SHARES,
    DIRECTORY_TRASH,
    DIRECTORY_JOBS,
}

Properties

---

FileType

The type of a UFile

enum class FileType {
    FILE,
    DIRECTORY,
    SOFT_LINK,
    DANGLING_METADATA,
}

Properties

---

UFileSpecification

__

data class UFileSpecification(
    val collection: String,
    val product: ProductReference,
)

Properties

---

FileMetadataOrDeleted.Deleted

Indicates that the metadata document has been deleted is no longer in use

data class Deleted(
    val id: String,
    val changeLog: String,
    val createdAt: Long,
    val createdBy: String,
    val status: FileMetadataDocument.Status,
    val type: String /* "deleted" */,
)

Properties

---

FileMetadataHistory

data class FileMetadataHistory(
    val templates: JsonObject,
    val metadata: JsonObject,
)

Properties

---

FileMetadataOrDeleted

sealed class FileMetadataOrDeleted {
    abstract val createdAt: Long
    abstract val createdBy: String
    abstract val id: String
    abstract val status: FileMetadataDocument.Status

    class FileMetadataDocument : FileMetadataOrDeleted()
    class Deleted : FileMetadataOrDeleted()
}

Properties

---

FilesStreamingSearchResult

sealed class FilesStreamingSearchResult {
    class EndOfResults : FilesStreamingSearchResult()
    class Result : FilesStreamingSearchResult()
}

---

FilesStreamingSearchResult.EndOfResults

data class EndOfResults(
    val type: String /* "end_of_results" */,
)

Properties

---

FilesStreamingSearchResult.Result

data class Result(
    val batch: List<UFile>,
    val type: String /* "result" */,
)

Properties

---

FindByPath

data class FindByPath(
    val id: String,
)

Properties

---

LongRunningTask

sealed class LongRunningTask {
    class Complete : LongRunningTask()
    class ContinuesInBackground : LongRunningTask()
}

---

LongRunningTask.Complete

data class Complete(
    val type: String /* "complete" */,
)

Properties

---

LongRunningTask.ContinuesInBackground

data class ContinuesInBackground(
    val taskId: String,
    val type: String /* "continues_in_background" */,
)

Properties

---

UFileIncludeFlags

data class UFileIncludeFlags(
    val includeOthers: Boolean?,
    val includeUpdates: Boolean?,
    val includeSupport: Boolean?,
    val includeProduct: Boolean?,
    val includePermissions: Boolean?,
    val includeTimestamps: Boolean?,
    val includeSizes: Boolean?,
    val includeUnixInfo: Boolean?,
    val includeMetadata: Boolean?,
    val filterCreatedBy: String?,
    val filterCreatedAfter: Long?,
    val filterCreatedBefore: Long?,
    val filterProvider: String?,
    val filterProductId: String?,
    val filterProductCategory: String?,
    val filterProviderIds: String?,
    val filterByFileExtension: String?,
    val path: String?,
    val allowUnsupportedInclude: Boolean?,
    val filterHiddenFiles: Boolean?,
    val filterIds: String?,
    val hideProductId: String?,
    val hideProductCategory: String?,
    val hideProvider: String?,
)

Properties

---

UFileUpdate

Describes an update to the Resource

data class UFileUpdate(
    val timestamp: Long,
    val status: String?,
)

Updates can optionally be fetched for a Resource. The updates describe how the Resource changes state over time. The current state of a Resource can typically be read from its status field. Thus, it is typically not needed to use the full update history if you only wish to know the current state of a Resource.

An update will typically contain information similar to the status field, for example:

• A state value. For example, a compute Job might be RUNNING.

• Change in key metrics.

• Bindings to related Resources.

Properties

---

UploadProtocol

enum class UploadProtocol {
    CHUNKED,
}

Properties

---

WriteConflictPolicy

A policy for how UCloud should handle potential naming conflicts for certain operations (e.g. copy)

enum class WriteConflictPolicy {
    RENAME,
    REJECT,
    REPLACE,
    MERGE_RENAME,
}

Properties

---

FilesCopyRequestItem

data class FilesCopyRequestItem(
    val oldId: String,
    val newId: String,
    val conflictPolicy: WriteConflictPolicy,
)

Properties

---

FilesCreateDownloadRequestItem

data class FilesCreateDownloadRequestItem(
    val id: String,
)

Properties

---

FilesCreateFolderRequestItem

data class FilesCreateFolderRequestItem(
    val id: String,
    val conflictPolicy: WriteConflictPolicy,
)

Properties

---

FilesCreateUploadRequestItem

data class FilesCreateUploadRequestItem(
    val id: String,
    val supportedProtocols: List<UploadProtocol>,
    val conflictPolicy: WriteConflictPolicy,
)

Properties

---

FilesMoveRequestItem

data class FilesMoveRequestItem(
    val oldId: String,
    val newId: String,
    val conflictPolicy: WriteConflictPolicy,
)

Properties

---

FilesStreamingSearchRequest

data class FilesStreamingSearchRequest(
    val flags: UFileIncludeFlags,
    val query: String,
    val currentFolder: String?,
)

Properties

---

FilesCreateDownloadResponseItem

data class FilesCreateDownloadResponseItem(
    val endpoint: String,
)

Properties

---

FilesCreateUploadResponseItem

data class FilesCreateUploadResponseItem(
    val endpoint: String,
    val protocol: UploadProtocol,
    val token: String,
)

Properties

---