List Folder Content#
Provides a list of files and sub-folders inside a given folders. To list top-level folders see List all Root Directories
POST https://api.cloudplan.net/api/folder/ls
Request Parameters#
{
"node_id": "",
"folder_id": "",
"number": 0,
"skip": 0,
"sort_modified": False,
"sort_size": False,
"sort_invert": False
"admin": False
"with_parent_docs": False
}
folder_id | (string)
The folder whose content will be listed. Can be any non-deleted root or sub folder.
node_id | (string)
List content of this specific node. Since content syncing is not instantaneous the data source can be picked by the caller. If left empty a suitable node is selected automatically with priority on the private cloud nodes.
Can be the id of any node that synchronizes the content of the requested folder.
number | (optional) (integer)
Return this maximum amount of folder documents.
default: 50
skip | (optional) (integer)
Skip this many folder documents. Together with number this implements paging of the result.
default: 0
sort_modified | (optional) (bool)
Sort the results by modified date instead of name.
default: False
sort_size | (optional) (bool)
Sort by total size of all items in the folder and its sub folders.
default: False
sort_invert | (optional) (bool)
Invert the sorting direction.
default: False
admin | (optional) (bool)
Run the request in admin-mode. If the calling user in a administrator for their organisation this will return all items where the organisation has permissions.
default: False
with_parent_docs | (optional) (bool)
For convenience it is possible to include the Folder Objects of all parent folders in the reply. This can be useful for displaying the complete path of items.
default: False
Reply Parameters#
{
"folder_id": "",
"parent_id": "",
"has_sub_folders": true,
"folder_name": "",
"user_rights": [
"view",
"read",
"write",
"delete",
"sync"
],
"admin_rights": [],
"folder_content": [],
"skip": 0,
"number": 0,
"node_doc": {}
}
folder_id | (string)
The id of the folder whose content is being listed.
parent_id | (string)
Id of the parent of the given folder. Useful for navigation.
has_sub_folders | (bool)
For convenience indicates the presence of sub folders, even if they are not included in the result due to paging.
folder_name | (string)
The display name of the listed folder.
user_rights | (list of string)
Indicates the permissions the calling user has for the content of this folder. A list with any of these:
viewreadwritedeletesync
admin_rights | (list of string)
Same ase user_rights but contains the permissions granted through admin status only.
folder_content | (list)
A list of File and Folder Index Objects.
skip | (integer)
The skip parameter from the request for conveniece.
number | (integer)
The number parameter from the request for conveniece.
Example#
This request will list all items in the given folder id.
{
"folder_id": "6319C982C7C0D952BFAA7347D212E57D"
}
{
"result": true,
"folder_id": "6319C982C7C0D952BFAA7347D212E57D",
"parent_id": "",
"has_sub_folders": true,
"folder_name": "big_files",
"user_rights": [
"view",
"read",
"write",
"delete",
"sync"
],
"admin_rights": [],
"folder_content": [
{
"cp_id": "6729D89570415228835B3A96AE798D4B",
"name": "cp_awsfs-1.2.5.tar.gz",
"type": "file",
"changed_by": "58B84023CC9C524F7441DAEE72BC9C73",
"changed_by_user": "56A23EB6998F303B134C1C0A723447B0",
"created": 1730795832,
"modified": 1730795832,
"file_size_kb_estimate": 83,
"file_size_b": 85463,
"last_block_size": 85463,
"tags": [],
"limited_admin_rights": null,
"limited_admin_right_folder_right_disallow": null
},
{
"cp_id": "6319CA1655723554207096C51B79DC26",
"name": "test folder",
"type": "folder",
"changed_by": "58B84023CC9C524F7441DAEE72BC9C73",
"changed_by_user": "56A23D90E7EC5FC6555CF21E9702AB20",
"created": 1662634519,
"modified": 1662634519,
"file_size_kb_estimate": 2222745,
"file_size_b": 0,
"last_block_size": 2778368,
"has_sub_folder": true,
"tags": [],
"limited_admin_rights": null,
"limited_admin_right_folder_right_disallow": null
}
],
"skip": 0,
"number": 20,
"node_doc": {
"cp_id": "58B84023CC9C524F7441DAEE72BC9C73",
"node_type": "cloud",
"node_name": "PCN 1"
}
}
File and Folder Index Objects#
These index objects represent either folders or files and differ slightly from the Folder Objects but are very similar.
{
"cp_id": "",
"name": "",
"type": "",
"changed_by": "",
"changed_by_user": "",
"created": 0,
"modified": 0,
"file_size_kb_estimate": 0,
"file_size_b": 0,
"has_sub_folder": false,
"tags": []
}
cp_id | (string)
The id of the given item.
If the item is a folder, this id is the folder id that can be used e.g. for another list call of it’s content.
Otherise it is the id of a file and can be used for file related api calls like Create a Weblink
name | (string)
Disply name of the given item.
type | (string)
Indicates wheter the item is a folder or a file. Possible values are:
filefolder
changed_by | (string)
The id of the node that last modified this item.
changed_by_user | (string)
The id of the user* that last modified this item. If the change occured on a node it is the owner of that node. If the change occured through the web portal this will be the logged in user.
created | (integer)
Unix timestamp in seconds for the time of the creation of the item. In few cases this can also be returned as a iso date string.
modified | (integer)
Unix timestamp in seconds for the time of the last modification of the item. In few cases this can also be returned as a iso date string.
file_size_kb_estimate | (integer)
Size of the file in Kilobytes.
file_size_b | (integer)
Size of the file in Bytes. Correctness is not guaranteed for very large files.
has_sub_folder | (bool)
Indicates whether this item is a folder which contains any sub folders.
tags | (list)
A list of tag objects that are assigend to the item.