- Home
- Resources
- Folders
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. |
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) |