API Documentation
Toggle TOC panel

URL structure

1 https://access-service.xy-company.com/api/v1/collections/{orgId}/collections

where {orgId} is the ID of an organisation.

Supported methods and overview

  • POST - creates a new folder (i.e. collection) within an organisation (specified by orgId), which involves specifying the following properties on the resulting folder:
    • The folder's location and name.
    • ( Optionally ) Collaborators (as well as their permission sets).

Detailed description

This API endpoint creates a new folder, which can be used to organize file objects/Secure Objects and other folders.

A folder/collection is analogous to an operating system's folders/directories on a file system. The Cocoon Data Platform's folders are used for organizing files and other folders logically in storage managed by the Content Service.

The Cocoon Data user whose account creates a new folder through this endpoint becomes the owner 1 of this folder. When creating this new folder, other than setting its required name and parent properties (through the name and parentId parameters respectively), collaborators and their permission sets (specified through this endpoint's collaborators parameter) can also be set - where a permission set is specific to each individual collaborator. For each collaborator, one of the following five permission sets can be applied:

1 Be aware that the ownership of a folder can be changed to that of another Cocoon Data user.

2 If any of these items are subsequently moved to a child folder on which a more restrictive permission set (listed above) has been applied for a given collaborator, then that collaborator will only possess the relevant permissions (granted by this more restrictive permission set) on this child folder and any other items contained within it. The exceptions are the Remove (File) and Remove (Folder) permissions, which are propagated down through a folder hierarchy, regardless of whether or not a more restrictive permission set has been applied to an item further down the hierarchy.

3 Relates to the active version of the file.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

  • Originator - when this user:
    • is a member of the organisation whose ID is specified by {orgId} in the request's URL and
    • will create and initially own the resulting folder.
  • Originator, Collaborator and Ad hoc - when the parentId parameter is specified for a folder (within the organisation specified by {orgId}) on which this user is a collaborator with the Create Folder permission.
    Note: Such a collaborator user cannot set this endpoint's collaborators parameter, unless this user also has the Share permission on the folder represented by parentId.

The Cocoon Data Platform's resources available to one of these Cocoon Data users (above) is determined by the access token submitted in the header of requests to this endpoint.

Required headers

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...
    where the Bearer token is the appropriate access token.
  • Content-Type: application/json

Required parameters

The following required parameters must be sent in the body of the POST request, as individual members of a JSON object:

  • name - The name to apply to the folder (in storage).
  • parentId - The ID of an existing folder (within the organisation specified by {orgId}) that will contain this new folder. Specifying a value of 0 results in the new folder being created at the logical root location in storage.
    Example (creating a collection at the root location in storage):
    "name": "Scenery",
    "parentId": "0"

Optional parameters

The following optional parameters can also be sent in the body of the POST request, each as individual members of the JSON object that includes the Required parameters above:

  • collaborators ( For collaborator users, requires the Share permission on parentId ) - A parameter containing the following optional sub-element parameters that relate to the collaborators being applied to this folder:
    • list - An array of elements about each collaborator, where each element of this array contains the following optional sub-elements:
      • email - The email address of the person to add as a collaborator to the folder. (Although this sub-element is optional, omitting it serves no purpose.)
      • permissionSet - The permission set to apply to this collaborator. This is done by specifying the ID of the permission set as a sub-element parameter of this parameter: Note: If this sub-element is omitted, then the View permission set is automatically applied to this collaborator.
    Tip: It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in its own object) because any modifications to one or more collaborators on an existing folder requires all collaborators and their permission sets to be specified in the request to modify a folder.
    Example (creating a new folder within an existing folder, while adding new collaborators each with different sets of permissions to this new folder):
    "name": "Large Files",
    "parentId": "876543210987654321"
    "collaborators": {
    "list": [
    "email": "chris.collaborator@xy-company.com",
    "permissionSet": {
    "id": 5
    "email": "olly.originator@xy-company.com",
    "permissionSet": {
    "id": 3
    "email": "adhoc.user@another-xy-company.com"
    Note: The permission set with an ID of 5 is Upload and with an ID of 3 is Modify. See <access-service>/api/v1/permissions/sets for more information about permission sets.


If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

  • id - The ID value of the created folder.
  • name - The name of the folder, which was set when the folder was created (using this endpoint).
  • createdAt - The date and time when the folder was created.
  • modifiedAt - The date and time when the folder was last modified, which should be the same as (or close to) that of createdAt above.
  • shared - A boolean value that indicates whether or not the folder has been shared with any collaborators.
  • parentId - The ID of the folder that contains this new folder. A value of 0 indicates that this new folder is located at the default logical root storage location.
    Example (response from creating a new folder within an existing folder):
    "id": "876543210191817161",
    "name": "Large Files",
    "createdAt": "2014-10-15T01:19:08.294Z",
    "modifiedAt": "2014-10-15T01:19:08.294Z",
    "shared": true,
    "parentId": "876543210987654321"