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
- Ceate or 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 => {
//...
});To create or update a shared link for a file use
folders.update(folderID, updates, callback)
method, passing a new shared_link value in the updates parameter.
client.folders.update('12345', {
shared_link: {
access: "open",
password: "do-not-use-this-password",
unshared_at: "2022-12-12T10:53:43-08:00",
vanity_name: "my-shared-link",
permissions: {
can_view: true,
can_download: true
}
}
}).then(folder => {
// ...
})This will make a shared link to be open to everyone, but users will need to provide password to access the folder.
This link will be unshared at "2022-12-12T10:53:43-08:00". By setting vanity_name we create custom URL
https://app.box.com/v/my-shared-link. Custom URLs should not be used when sharing sensitive content as vanity URLs are
a lot easier to guess than regular shared links.
Additionally, everyone who has this link can view and download the folder.
You can create shared link using default values
client.folders.update('12345', {
shared_link: {}
}).then(folder => {
// ...
})- Default
accessvalue comes from the access level specified by the enterprise admin. - Default
password,unshared_at,vanity_namewill be empty. - Default
permissionsallows to view and download folder.
You can remove any field set on a link by sending value null (or empty object when it comes to permissions).
This will cause it's value to be default. For example, let's remove access and permissions:
client.folders.update('12345', {
shared_link: {
access: null,
permissions: {}
}
}).then(folder => {
// ...
})This will remove open access, and it will fall back to default value set by the enterprise admin.
The permissions we set on a shared link will be removed and default permissions will be applied.
Other properties of the shared link will not be changed as we are not sending them.
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.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 => {
// ...
})