API: Retrieving lists of files and folders
| Target URL | /api.php/Drive/files/browse |
| Required scope | list |
| HTTP Method | GET/POST |
| Output format | JSON |
Request Parameters Reference
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | The FileRun path of the folder. See this page |
| itemType | string | No | files lists only the files, folders only the folders. Left out, both are listed. |
| details | array | No | The information to include for each item, see below. Sent as details[]=mdate&details[]=fileSize. |
| limit | integer | No | The maximum number of items to return. 0, the default, returns all of them. |
| start | integer | No | The number of items to skip, for paging. |
The recursive parameter of older versions is no longer supported. A request which sends it is refused.
The response
data.meta describes the listed folder: path, parentPath (null at the top level) and folderName.
data.files holds one entry per item. Each entry has filename, relativePath (the FileRun path of the item, to use in further requests) and is_dir (1 for a folder, 0 for a file), plus the requested details. A detail is left out of an item when it does not apply to it, or when the account lacks the permission it depends on. The details which come from the metadata of the item are left out of items which carry no metadata at all.
| Detail | Applies to | Description |
|---|---|---|
| mdate | files, folders | The modification time, as a Unix timestamp |
| mdateHuman | files, folders | The modification time in a friendly format. Requires mdate as well. |
| cdate | files, folders | The creation time, as a Unix timestamp (0 for the home folder) |
| cdateHuman | files, folders | The creation time in a friendly format. Requires cdate as well. |
| fullPath | files, folders | The absolute path of the item on the server. Answered to administrator accounts only. |
| isShared | files, folders | 1 if the item is shared with other users. Requires the sharing permission. |
| hasWebLink | files, folders | 1 if a web link is attached to the item. Requires the web link permission. |
| weblink | files, folders | The URL of the web link, when one is attached. Requires the web link permission. |
| weblink-full | files, folders | The web link as an object: id, url, short_url, expiry, password, download_limit. Requires the web link permission. |
| description | files, folders | The description of the file type ("Folder" for folders) |
| color | folders | The folder color, when set and folder colors are enabled. Requires the metadata permission. |
| ext | files | The file extension |
| type | files | The type of the file, as defined in the file types configuration |
| fileSize | files | The size in bytes |
| nicerFileSize | files | The size, formatted |
| isLocked | files | 1 if the file is locked. Requires the download permission. |
| version | files | The current version number of the file. Requires the download permission. |
| hasThumb | files | Whether a thumbnail can be generated for the file. Requires the download permission. |
| hasStar | files, folders | 1 if the item is starred by the account. Requires the starring permission. |
| commentsCount | files, folders | The number of comments. Requires the permission to read comments. |
| tags | files, folders | The tags, each with id, text and color. Requires the metadata permission. |
| rating | files, folders | The rating, null when not rated. Requires the metadata permission. |
| metadataFileType | files, folders | The id of the metadata file type, null when none is set. Requires the metadata permission. |
The details uuid, icon and label of older versions are no longer available.
Virtual locations, such as the list of collections or the tag folders of the media section, answer with filename and relativePath only, plus cdate, cdateHuman and hasWebLink for collections and color for tags.
Example
Listing only the files of the home folder, with a formatted file size and the URL of the attached web link:
1path=/ROOT/HOME
2itemType=files
3details[]=nicerFileSize
4details[]=weblink
Expected output:
1{
2 "success": true,
3 "data": {
4 "meta": {
5 "path": "/ROOT/HOME",
6 "parentPath": "/ROOT",
7 "folderName": "Home Folder"
8 },
9 "files": [
10 {
11 "filename": "FileRun_Admin_Guide.pdf",
12 "relativePath": "/ROOT/HOME/FileRun_Admin_Guide.pdf",
13 "weblink": "https://amsterdam.demo.filerun.com/wl/?id=89M",
14 "is_dir": 0,
15 "nicerFileSize": "123 KB"
16 },
17 {
18 "filename": "Welcome.jpg",
19 "relativePath": "/ROOT/HOME/Welcome.jpg",
20 "is_dir": 0,
21 "nicerFileSize": "17 KB"
22 }
23 ]
24 }
25}