Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.).
- Folders
- Get a Folder's Information
- Get a Folder's Items
- Update a Folder's Information
- Create a Folder
- Copy a Folder
- Move a Folder
- Rename a Folder
- Delete a Folder
- Lock a folder
- Get All Locks on a Folder
- Delete a Lock on a Folder
- Find a Folder for a Shared Link
- Create a Shared Link
- Update a Shared Link
- Get a Shared Link
- Remove a Shared Link
Folder information can be retrieved by calling the
folders.get(folderID, options, callback)
method. Use the fields option to specify the desired fields.
client.folders.get('11111')
.then(folder => {
/* folder -> {
type: 'folder',
id: '11111',
sequence_id: '1',
etag: '1',
name: 'Pictures',
created_at: '2012-12-12T10:53:43-08:00',
modified_at: '2012-12-12T11:15:04-08:00',
description: 'Some pictures I took',
size: 629644,
path_collection:
{ total_count: 1,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' } ] },
created_by:
{ type: 'user',
id: '22222',
name: 'Example User'
login: '[email protected]' },
modified_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
owned_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
shared_link: null,
parent:
{ type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
item_status: 'active',
item_collection:
{ total_count: 1,
entries:
[ { type: 'file',
id: '33333',
sequence_id: '3',
etag: '3',
sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
name: 'tigers.jpeg' } ],
offset: 0,
limit: 100 } }
*/
});Requesting information for only the fields you need can improve performance and reduce the size of the network request.
client.folders.get(
'12345',
{ fields: 'name,shared_link,permissions,collections,sync_state' }
).then(folder => {
// ...
});The user's root folder can be accessed by calling the
folders.get(folderID, options, callback)
method with the folderID value of '0'.
client.folders.get('0')
.then(rootFolder => {
// ...
});Folder items can be retrieved by calling the
folders.getItems(folderID, options, callback)
method. This method supports offset-based pagination and marker-based pagination. To use offset-based pagination, do not pass in the usemarker parameter or set it to false. To use marker-based pagination, pass in the usemarker parameter as true. Use the fields option to specify the desired fields, and limit and (offset or marker) to control result set paging. Requesting information for only the fields you need can improve performance by reducing the size of the network response.
client.folders.getItems(
'12345',
{
usemarker: 'false',
fields: 'name',
offset: 0,
limit: 25
})
.then(items => {
/* items -> {
total_count: 2,
entries:
[ { type: 'folder',
id: '11111',
sequence_id: '1',
etag: '1',
name: 'Personal Documents' },
{ type: 'file',
id: '22222',
sequence_id: '0',
etag: '0',
name: 'Q2 Strategy.pptx' } ],
offset: 0,
limit: 25,
order:
[ { by: 'type', direction: 'ASC' },
{ by: 'name', direction: 'ASC' } ] }
*/
});Updating a folder's information is done by calling the
folders.update(folderID, updates, callback)
method. Use the updates parameter to specify the fields to update and their new values.
client.folders.update('11111', {name: 'Pictures from 2017'})
.then(updatedFolder => {
/* updatedFolder -> {
type: 'folder',
id: '11111',
sequence_id: '1',
etag: '1',
name: 'Pictures from 2017',
created_at: '2012-12-12T10:53:43-08:00',
modified_at: '2012-12-12T11:15:04-08:00',
description: 'Some pictures I took',
size: 629644,
path_collection:
{ total_count: 1,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' } ] },
created_by:
{ type: 'user',
id: '22222',
name: 'Example User'
login: '[email protected]' },
modified_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
owned_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
shared_link: null,
parent:
{ type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
item_status: 'active',
item_collection:
{ total_count: 1,
entries:
[ { type: 'file',
id: '33333',
sequence_id: '3',
etag: '3',
sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
name: 'tigers.jpeg' } ],
offset: 0,
limit: 100 } }
*/
});If you want to ensure that your update does not overwrite any other updates (i.e. to prevent against possible race
conditions), you can pass the last known value of the folder's etag field via the etag option; this will generate
an error if the folder was modified between when you read that etag value and when your updates are processed by the
API.
client.folders.update('22222', { name: 'Renamed Folder', etag: '5', fields: 'name' })
.then(updatedFolder => {
/* updatedFolder -> {
type: 'folder',
id: '22222',
sequence_id: '1',
etag: '6',
name: 'Renamed Folder' }
*/
})
.catch(err => {
if (err.statusCode === 412) {
// Precondition failed — the folder was modified before the update was processed
// Read the folder again to ensure it is safe to update and then retry
}
});Create a child folder by calling the folders.create(parentFolderID, newFolderName, callback) method.
client.folders.create('0', 'New Folder')
.then(folder => {
/* folder -> {
type: 'folder',
id: '123456',
sequence_id: '0',
etag: '0',
name: 'New Folder',
created_at: '2012-12-12T10:53:43-08:00',
modified_at: '2012-12-12T11:15:04-08:00',
description: '',
size: 0,
path_collection:
{ total_count: 1,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' } ] },
created_by:
{ type: 'user',
id: '22222',
name: 'Example User'
login: '[email protected]' },
modified_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
owned_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
shared_link: null,
parent:
{ type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
item_status: 'active',
item_collection:
{ total_count: 0,
entries: [],
offset: 0,
limit: 100 } }
*/
});Call the
folders.copy(sourceFolderID, destinationFolderID, callback)
method to copy a folder into another folder.
client.folders.copy('11111', '22222')
.then(folderCopy => {
/* folderCopy -> {
type: 'folder',
id: '1234567',
sequence_id: '0',
etag: '0',
name: 'Pictures from 2017',
created_at: '2012-12-12T10:53:43-08:00',
modified_at: '2012-12-12T11:15:04-08:00',
description: 'Some pictures I took',
size: 629644,
path_collection:
{ total_count: 1,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
{ type: 'folder',
id: '22222',
sequence_id: '3',
etag: '3',
name: 'Archives' } ] },
created_by:
{ type: 'user',
id: '22222',
name: 'Example User'
login: '[email protected]' },
modified_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
owned_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
shared_link: null,
parent:
{ type: 'folder',
id: '22222',
sequence_id: '3',
etag: '3',
name: 'Archives' },
item_status: 'active',
item_collection:
{ total_count: 1,
entries:
[ { type: 'file',
id: '44444',
sequence_id: '0',
etag: '0',
sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
name: 'tigers.jpeg' } ],
offset: 0,
limit: 100 } }
*/
});An optional name parameter can also be passed to rename the folder on copy. This can be
used to avoid a name conflict when there is already an item with the same name in the
target folder.
client.folders.copy('12345', '0', {name: 'Renamed folder'})
.then(folderCopy => {
// ...
});Call the folders.move(sourceFolderID, destinationFolderID, callback) method with the destination you want the folder moved to.
var folderID = '11111';
var destinationFolderID = '22222';
client.folders.move(folderID, destinationfolderID)
.then(folder => {
/* folder -> {
type: 'folder',
id: '11111',
sequence_id: '1',
etag: '1',
name: 'Pictures from 2017',
created_at: '2012-12-12T10:53:43-08:00',
modified_at: '2012-12-12T11:15:04-08:00',
description: 'Some pictures I took',
size: 629644,
path_collection:
{ total_count: 1,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
{ type: 'folder',
id: '22222',
sequence_id: '3',
etag: '3',
name: 'Archives' } ] },
created_by:
{ type: 'user',
id: '22222',
name: 'Example User'
login: '[email protected]' },
modified_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
owned_by:
{ type: 'user',
id: '22222',
name: 'Example User',
login: '[email protected]' },
shared_link: null,
parent:
{ type: 'folder',
id: '22222',
sequence_id: '3',
etag: '3',
name: 'Archives' },
item_status: 'active',
item_collection:
{ total_count: 1,
entries:
[ { type: 'file',
id: '33333',
sequence_id: '3',
etag: '3',
sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
name: 'tigers.jpeg' } ],
offset: 0,
limit: 100 } }
*/
});Use the folders.update(folderID, updates, callback) method to rename a folder by passing a new name for the folder in updates.name.
client.folders.update('12345', {name: 'New Name'}, callback);A folder can be deleted with the folders.delete(folderID, options, callback) method.
client.folders.delete('12345', {recursive: true})
.then(() => {
// deletion succeeded — no value returned
});Use the folders.lock(folderID, callback) to lock a folder
var folderID = '11111';
client.folders.lock(folderID)
.then(folderLock => {
/* folderLock -> {
"id": "12345678",
"type": "folder_lock",
"created_at": "2020-09-14T23:12:53Z",
"created_by": {
"id": "11446498",
"type": "user"
},
"folder": {
"id": "12345",
"type": "folder",
"etag": "1",
"name": "Contracts",
"sequence_id": "3"
},
"lock_type": "freeze",
"locked_operations": {
"delete": true,
"move": true
}
}
*/
});Use the folders.getLocks(folderID, callback) to get all locks on a folder.
var folderID = '11111';
client.folders.getLocks(folderID)
.then(folderLocks => {
/* folderLocks -> {
"entries": [
{
"folder": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
},
"id": "12345678",
"type": "folder_lock",
"created_by": {
"id": "11446498",
"type": "user"
},
"created_at": "2020-09-14T23:12:53Z",
"locked_operations": {
"move": true,
"delete": true
},
"lock_type": "freeze"
}
],
"limit": 1000,
"next_marker": null
}
*/
});Use the folders.deleteLock(folderLockID, callback) method to delete a folder lock.
var folderLockID = '12345';
client.folders.deleteLock(folderLockID)
.then(() => {
// deletion succeeded — no value returned
});To find a folder given a shared link, use the
sharedItems.get(url, password, options, callback)
method.
client.sharedItems.get(
'https://app.box.com/s/gjasdasjhasd',
'letmein'
),then(folder => {
//...
});You can create a shared link for a folder by calling the
folders.update(folderID, updates, callback)
method, passing a new shared_link value in the updates parameter.
client.folders.update('12345', {
shared_link: {
access: client.accessLevels.OPEN,
permissions: {
can_download: false
}
}
}).then(folder => {
// ...
})A set of shared link access level constants are available through the SDK for convenience:
accessLevels.OPENaccessLevels.COLLABORATORSaccessLevels.COMPANYaccessLevels.DEFAULTaccessLevels.DISABLED
You can update a shared link for a folder by calling the
folders.update(folderID, updates, callback)
method, passing a new shared_link value in the updates parameter.
client.folders.update('12345', {
shared_link: {
access: client.accessLevels.COMPANY,
permissions: {
can_download: true
}
}
}).then(folder => {
// ...
})To check for an existing shared link on a folder, inspect the
shared_link field on a folder object.
This object, when present, contains a unicode string containing the shared
link URL.
client.folders.get('11111', { fields: 'shared_link' })
.then(folder => {
let url = folder.shared_link.download_url
//...
})A shared link for a folder can be removed calling
folders.update(folderID, updates, callback)
with null for the shared_link value.
client.folders.update('12345', {
shared_link: null
}).then(folder => {
// ...
})