Folders Resource

GET /folders

Get folders by ID.

Request Parameters
name type description default constraints multivalued
count query 100 int no
description_format query The desired format for the binder descriptions. Can be "html" or "text". text   no
first query 0 int no
id query The ID of a folder. Can be specified multiple times.   long yes
Response Body
media type data type description
application/json SearchResultList (JSON) A SearchResultList of BinderBrief objects.
application/xml searchResultList (XML)

DELETE /folders/{id}

Delete the specifed binder object.

Personal storage folders are moved to the trash by default. purge=true will delete the folder permanently instead. Folders on external storage (net folders, mirrored folders) are always deleted permanantly.

Request Parameters
name type description default constraints
id path The ID of the binder to delete.   long
only_if_empty query Only delete the folder if it is empty. false boolean
purge query Whether the binder will be deleted permanently (true) or moved to the trash (false). false boolean
Response Codes
code condition
409 (BINDER_NOT_EMPTY) The binder is not empty.

GET /folders/{id}

Get the binder with the specified ID.

Request Parameters
name type description default constraints
id path The ID of the binder to return.   long
description_format query The desired format for the binder description. Can be "html" or "text". text  
include_attachments query Configures whether attachments should be included in the returned binder object. true boolean
library_info query Whether to calculate and return binder statistics such as total size on disk. false boolean
Response Codes
code condition
404 (BINDER_NOT_FOUND) The binder does not exist.
Response Body
media type data type description
application/json Binder (JSON) Returns a subclass of Binder.
application/xml binder (XML)

PUT /folders/{id}

Update a binder.

Request Parameters
name type description default constraints
id path The ID of the binder.   long
description_format query The desired format for the children descriptions. Can be "html" or "text". text  
include_attachments query Whether to return attachments in the response. true boolean
Request Body
media type data type description
application/json Binder (JSON) The new binder object.
application/xml binder (XML)
Response Body
media type data type description
application/json Binder (JSON) The updated binder object.
application/xml binder (XML)

GET /folders/{id}/access

Get the rights that the authenticated user has to the binder.

Request Parameters
name type description constraints
id path The ID of the binder. long
Response Body
media type data type description
application/json Access (JSON) An Access object.
application/xml access (XML)

GET /folders/{id}/ancestry

Get all of the parent binders of the binder. The top workspace is the first item and the immediate parent is the last item.

For example, the ancestry of "/Home Workspace/Personal Workspaces/Bob Barker (bbarker)/A/B" is:

  • /Home Workspace
  • /Home Workspace/Personal Workspaces
  • /Home Workspace/Personal Workspaces/Bob Barker (bbarker)
  • /Home Workspace/Personal Workspaces/Bob Barker (bbarker)/A

Request Parameters
name type description constraints
id path The ID of the binder. long
Response Body
media type data type description
application/json array of BinderBrief (JSON) A list of BinderBrief objects.
application/xml list of binderBrief (XML)

GET /folders/{id}/library_changes

Get changes to files and folders that have occurred since the specified date.

Request Parameters
name type description default constraints
id path The ID of the folder.   long
count query The maximum number of changes to return. 500 int
description_format query The desired format for descriptions. Can be "html" or "text". text  
recursive query Whether to return changes in the immediate folder only (false) or all subfolders (true). true boolean
since query UTC date and time in ISO 8601 format. For example, 2016-03-05T06:24:57Z.    
Response Codes
code condition
409 The changes cannot be determined.
Response Body
media type data type description
application/json BinderChanges (JSON) A BinderChanges resource.
application/xml binderChanges (XML)

GET /folders/{id}/library_children

List the children of a binder.

The title query parameter limits the results to those children with the specified name. Wildcards are not supported.

Request Parameters
name type description default constraints
id path The ID of the binder.   long
allow_jits query Whether to trigger JITS, if applicable. true boolean
count query The maximum number of results to return. 100 int
description_format query The desired format for the children descriptions. Can be "html" or "text". text  
first query The index of the first result to return. 0 int
title query The name of the child to return,    
Response Body
media type data type description
application/json object (JSON) A SearchResultList of SearchableObjects (BinderBriefs and FileProperties).
application/xml anyType (XML)

GET /folders/{id}/library_entities

Search for entities by keyword.

Request Parameters
name type description default constraints
id path The ID of the folder to search.   long
binders query Whether to include binders in the results. true boolean
count query The maximum number of results to return. 100 int
description_format query The desired format for the binder description. Can be "html" or "text". text  
files query Whether to include files in the results. true boolean
first query The index of the first result to return. 0 int
folder_entries query Whether to include folder entries in the results. true boolean
keyword query A search term. May include wildcards, but cannot begin with a wildcard. For example, "keyword=D*d" is allowed but "keyword=*d" is not.    
parent_binder_paths query Whether to include the parent binder path with each entity. false boolean
recursive query Whether to search the immediate folder (false) or all subfolders (true). false boolean
replies query Whether to include replies in the results. true boolean
Response Body
media type data type description
application/json SearchResultList (JSON) A SearchResultList of SearchableObject resources (BinderBrief, FolderEntryBrief, FileProperties, ReplyBrief).
application/xml searchResultList (XML)

GET /folders/{id}/library_files

List the child files of a binder.

Request Parameters
name type description default constraints
id path The ID of the binder.   long
count query The maximum number of results to return.   int
file_name query The name of the child to return,    
first query The index of the first result to return.   int
parent_binder_paths query If true, the path of the parent binder is included in each result. false boolean
recursive query Whether to search the binder and sub-binders for files. false boolean
Response Body
media type data type description
application/json object (JSON) A SearchResultList of SearchableObjects (BinderBriefs and FileProperties).
application/xml anyType (XML)

POST /folders/{id}/library_files

Add a file to the specified folder. The request Content-Type can be anything except x-www-form-urlencoded. Supports multipart/form-data posts (see here). If another Content-Type is specified (application/octet-stream, for example), the raw bytes of the request body are read and stored as the file content.

Request Parameters
name type description default constraints
id path The ID of the folder where the file is to be added.   long
file_name query The name of the file to create.    
md5 query The MD5 checksum of the file. If specified, the REST interface returns an error if the MD5 checksum of the uploaded content does not match the expected value.    
mod_date query The desired last modified time for the new file.    
overwrite_existing query If a file already exists with the specified name, this specifies whether to overwrite the file (true) or fail with an error (false). false boolean
Response Codes
code condition
404 (FOLDER_NOT_FOUND) The target folder does not exist.
409 (FILE_EXISTS) A file with the specified name already exists in the target folder (if overwrite_existing is false.
Response Body
media type data type
application/json FileProperties (JSON)
application/xml fileProperties (XML)

POST /folders/{id}/library_files

Copy a file into the specified folder.

The Content-Type must be application/x-www-form-urlencoded. The parameter values in the form data should be URL-encoded UTF-8 strings. For example: source_id=09c1c3fb530f562401531070137b000e&file_name=H%C3%B6wdy.

Request Parameters
name type description constraints
file_name form The name of the new file.  
source_id form The ID of the source file to copy.  
id path The ID of the target folder. long
Response Codes
code condition
404 (FOLDER_NOT_FOUND) The target folder does not exist.
404 (FILE_NOT_FOUND) The source file does not exist.
409 (FILE_EXISTS) A file with the specified name already exists in the target folder.
Response Body
media type data type description
application/json FileProperties (JSON) The new file metadata.
application/xml fileProperties (XML)

GET /folders/{id}/library_folders

List the child folders of a binder.

The title query parameter limits the results to those folders with the specified name. Wildcards are not supported.

Request Parameters
name type description default constraints
id path The ID of the binder.   long
count query The maximum number of results to return. 100 int
description_format query The desired format for the children descriptions. Can be "html" or "text". text  
first query The index of the first result to return. 0 int
title query The name of the child to return,    
Response Body
media type data type description
application/json object (JSON) A SearchResultList of SearchableObjects (BinderBriefs and FileProperties).
application/xml anyType (XML)

POST /folders/{id}/library_folders

Create a new folder.

Request Parameters
name type description default constraints
id path The ID of the binder where the folder should be createad..   long
description_format query The desired format for the folder description in the response. Can be "html" or "text". text  
Request Body
media type data type description
application/json BinderBrief (JSON) The BinderBrief object to be created. Minimally, you must specify the "title".
application/xml binderBrief (XML)
Response Body
media type data type description
application/json Folder (JSON) The new Folder object.
application/xml folder (XML)

POST /folders/{id}/library_folders

Copy a folder into the specified binder.

The Content-Type must be application/x-www-form-urlencoded. The title value in the form data should be a URL-encoded UTF-8 string. For example: source_id=48&title=H%C3%B6wdy.

Request Parameters
name type description default constraints
source_id form The ID of the source folder to copy.   long
title form The name of the new binder.    
id path The ID of the target folder.   long
description_format query text  
Response Body
media type data type description
application/json Folder (JSON) The new binder metadata.
application/xml folder (XML)

GET /folders/{id}/library_tree

Get a tree structure representing the folder structure contained in this binder.

Request Parameters
name type description default constraints
id path The ID of the binder.   long
description_format query The desired format for the binder descriptions. Can be "html" or "text". text  
Response Body
media type data type description
application/json BinderTree (JSON) A BinderTree
application/xml binderTree (XML)

POST /folders/{id}/parent_binder

Move the specified binder. The Content-Type must be application/x-www-form-urlencoded.

Request Parameters
name type description default constraints
binder_id form The ID of the target binder.   long
id path The binder to move.   long
description_format query The desired format for the binder description. Can be "html" or "text". text  
include_attachments query Whether to include the binder attachments in the response. true boolean
Response Body
media type data type description
application/json Binder (JSON) The modified binder object.
application/xml binder (XML)

GET /folders/{id}/recent_activity

List recently changed folder entries in the specified binder.

Request Parameters
name type description default constraints
id path The ID of the folder or workspace.   long
count query The maximum number of results to return. 20 int
description_format query The desired format for the folder entry description. Can be "html" or "text". text  
first query The index of the first result to return. 0 int
parent_binder_paths query Whether to include the parent binder path with each entry. false boolean
Response Body
media type data type description
application/json SearchResultList (JSON) A SearchResultList of RecentActivityEntry resources.
application/xml searchResultList (XML)

GET /folders/{id}/shares

Get information about the users and groups with whom the authenticated user has shared the binder.

Request Parameters
name type description constraints
id path The ID of the binder. long
Response Body
media type data type description
application/json SearchResultList (JSON) A SearchResultList of Share resources.
application/xml searchResultList (XML)

POST /folders/{id}/shares

Share the binder with another user or group. Minimally, you must specify the Share recipient and access role.

If the authenticated user has already shared the folder with the specified recipient, this will overwrite the previous share settings.

Request Parameters
name type description default constraints
id path The ID of the folder entry.   long
notify query If true, the recipient will be notified by email. false boolean
Request Body
media type data type description
application/json Share (JSON) The share object to create.
application/xml share (XML)
Response Body
media type data type description
application/json Share (JSON) The newly created Share resource.
application/xml share (XML)

POST /folders/{id}/title

Rename the specified binder. The Content-Type must be application/x-www-form-urlencoded. The value of the title form parameter in the request body should be a UTF-8 string that has been URL encoded.

Request Parameters
name type description default constraints
title form The new name of the binder.    
id path The binder to rename.   long
description_format query The desired format for the binder description. Can be "html" or "text". text  
include_attachments query Whether to include the binder attachments in the response. true boolean
Response Codes
code condition
409 (TITLE_EXISTS) A binder with the specified name already exists.
Response Body
media type data type description
application/json Binder (JSON) The modified binder object.
application/xml binder (XML)