> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# <access-service>/api/v1/collections/{collectionId}

## URL structure&#x20;

```text theme={null}
https://access-service.xy-company.com/api/v1/collections/{collectionId}
```

where `{collectionId}` is the ID of a collection.

## Supported methods and overview&#x20;

* `GET` - used to retrieve information about a [collection](/3.1/api/creating-secure-objects-and-collections.md#collection), based on the collection's ID.
* `PUT` - used to modify a collection's attributes/metadata, which involves the owner<sup>1</sup> of this collection performing *any combination* of the following:

  * Modifying the collaborators (as well as their [permission sets](/3.1/api/access-service-api-v1-permissions-sets.md)) on a collection.
  * Moving and renaming the collection. \

    **Note:** A collaborator on the collection (with the **Manage** *permission set*) can also perform these actions.
* `DELETE` - used to delete a collection. Unlike [deleting Secure Objects](/3.1/api/access-service-api-v1-objects-objectid.md), deleting a collection removes all trace of the collection and its attributes/metadata from the Covata Platform.

> [!NOTE]
>
> Both the `GET` and `DELETE` methods take no parameters.

<sup>1</sup> A collection's owner is the [Covata user](/3.1/admin/administering-users.md) whose account was used to [create the collection](/3.1/api/access-service-api-v1-collections.md). (A collection's ownership [can also be changed](/3.1/api/content-service-api-v1-items-transfer.md) to that of another Covata user.)

## Detailed description&#x20;

This API endpoint serves a number of purposes:

* Retrieves information about a collection, using the collection's ID. A collection's ID can be obtained by calling the [\<access-service>/api/v1/items](/3.1/api/access-service-api-v1-items.md) API endpoint, which retrieves a list of information associated with collections that can be filtered using various 'search' criteria.
* Allows the collection's owner<sup>2</sup> to modify the collection's attributes/metadata, which include the following:

  * Parent collection (specified through this endpoint's **parentId** parameter) - the collection to which this collection (whose ID is specified in the `{collectionId}` part of this request's URL) will be moved.
  * Name (specified through this endpoint's **name** parameter) - the name of this collection.
  * Collaborators and their [permission sets](/3.1/api/access-service-api-v1-permissions-sets.md) (specified through this endpoint's **collaborators** [parameter](/3.1/api/access-service-api-v1-collections-collectionid.md#access-service-api-v1-collections-collectionid-optional-parameters)) - where a *permission set* is specific to each individual collaborator. For each collaborator, one of the following four *permission sets* can be applied:

    * **Download** - grants the collaborator the following [permissions](/3.1/api/access-service-api-v1-permissions-sets.md) on any Secure Objects<sup>3</sup> contained within this collection:

      * **Download** the Secure Object's content (by calling the `GET` method on the [\<content-service>/api/v1/objects/\{objectId}/contents](/3.1/api/content-service-api-v1-objects-objectid-contents.md) endpoint).
      * **Print** and **View** the Secure Object's content from a Safe Share application's [content viewer](/3.1/user/accessing-secure-content.md#viewing-and-printing-secure-content). The **View** *permission* also allows the Secure Object's *read-only view* to be downloaded (by calling the `GET` method on the [\<content-service>/api/v1/objects/\{objectId}/view](/3.1/api/content-service-api-v1-objects-objectid-view.md) endpoint).
    * **Manage** - grants the collaborator the following *permissions* to perform any of the following actions on any Secure Objects<sup>3</sup> contained within this collection and/or the content of these Secure Objects in the owner's storage space:

      * **Download** the Secure Object's content.
      * Delete the Secure Object and its content (by calling the `DELETE` method on the [\<content-service>/api/v1/objects/\{objectId}/contents](/3.1/api/content-service-api-v1-objects-objectid-contents.md) endpoint followed by the `DELETE` method on the [\<access-service>/api/v1/objects/\{objectId}](/3.1/api/access-service-api-v1-objects-objectid.md) endpoint), through the **Remove (File)** *permission*.
      * **Move** the Secure Object to a different collection *within* a *common collection hierarchy* (by calling the `PUT` method on the [\<access-service>/api/v1/objects/\{objectId}](/3.1/api/access-service-api-v1-objects-objectid.md) endpoint). A *common collection hierarchy* is a collection hierarchy that contains either this new collection or the Secure Object (subsequently contained within this new collection), where the owner of this item has also added the same collaborator (with the **Manage** *permission set*) to the collection hierarchy's parent (i.e. the root-level) collection.
      * **Print** the Secure Object's content from the Safe Share web application's content viewer.
      * **Rename** the Secure Object (by calling the `PUT` method on the [\<access-service>/api/v1/objects/\{objectId}](/3.1/api/access-service-api-v1-objects-objectid.md) endpoint).
      * **View** the Secure Object's content in a Safe Share application's content viewer, which also allows the Secure Object's *read-only view* to be downloaded.

      The **Manage** *permission set* also grants the collaborator the ability to perform the following within this collection (as the parent collection):

      * Initialize a new *Incomplete* Secure Object or create a new completed Secure Object (whose state is *Created*) within this parent collection, through the **Upload File** *permission*. This is achieved by calling the `POST` method on the [\<access-service>/api/v1/objects](/3.1/api/access-service-api-v1-objects.md) endpoint with the **parentId** parameter value being that of this parent collection *and* either with or without the Secure Object's SHA512 value.
      * Create a new child collection within this parent collection, through the **Create Folder** *permission*. This is achieved by calling the [\<access-service>/api/v1/collections](/3.1/api/access-service-api-v1-collections.md) endpoint with the **parentId** parameter value being that of this parent collection.
      * Delete a child collection and its content within this parent collection, through the **Remove (Folder)** *permission*. This is achieved by calling the `DELETE` method on this endpoint with the **parentId** parameter value being that of this parent collection and the child collection specified in the `{collectionId}` part of the request's URL. \

        **Important:** Be aware that a more restrictive *permission set* applied to any items contained within this child collection being deleted are ignored and as such, these items will also be deleted.
    * **Upload** - grants the collaborator the following *permissions* to perform any of the following actions on any Secure Objects<sup>3</sup> contained within this collection and/or the content of these Secure Objects in the owner's storage space:

      * **Download** the Secure Object's content.
      * **Print** and **View** the Secure Object's content from a Safe Share application's content viewer, which also allows the Secure Object's *read-only view* to be downloaded.

      The **Upload** *permission set* (which grants the **Upload File** *permission*) also grants the collaborator the ability to initialize a new *Incomplete* Secure Object or create a new completed Secure Object (whose state is *Created*) within this new collection (as a parent collection), once this collection has been created.
    * **View** - grants the collaborator the **View** *permission* on any Secure Objects<sup>3</sup> contained within this collection, which allows these Secure Objects':

      * content to be viewed from a Safe Share application's content viewer, as well as
      * *read-only views* to be downloaded.
* Deletes a collection. This has the following effects:

  * The collection (including any other collections contained within it) are deleted from the database of the Covata Platform's Access Service. Hence, the attributes/metadata associated with these collections will no longer be available.
  * The state of all Secure Objects that were contained within the collection are changed to *Deleted*. The encrypted data associated with these Secure Objects contained in storage (i.e. the encrypted data managed by the Covata Platform's Content Service) is also physically deleted (see **Note** below). However, the attributes/metadata associated with these Secure Objects are still retained by the Access Service.

  **Note:** The encrypted data of all Secure Objects contained within the collection (deleted via this endpoint) is also automatically deleted from storage by the Content Service. However, this process only occurs every two hours (by default) or when a new access token (belonging to the owner of this collection and excluding those obtained through a refresh token) is passed in the [header](/3.1/api/access-service-api-v1-collections-collectionid.md#access-service-api-v1-collections-collectionid-required-headers) of requests to this endpoint. Therefore, it is strongly advised that you first explicitly [delete this data in storage](/3.1/api/content-service-api-v1-collections-collectionid-contents.md) *before* calling this API endpoint with the `DELETE` method (to change the state of all Secure Objects contained within the collection to *Deleted*). If not, then the [Covata user](/3.1/admin/administering-users.md)'s actual quota will differ from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service).

<sup>2</sup> A collection's owner is the Covata user whose account was used to [create the collection](/3.1/api/access-service-api-v1-collections.md). (A collection's ownership [can also be changed](/3.1/api/content-service-api-v1-items-transfer.md) to that of another Covata user.)

<sup>3</sup> If any of these Secure Objects are subsequently contained within a nested (i.e. child) collection to 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 collection and any other items contained within it. The exceptions are the **Remove (File)** and **Remove (Folder)** *permissions*, which are propagated down through a collection hierarchy, regardless of whether or not a more restrictive *permission set* has been applied to an item further down the hierarchy.

## Supported roles and conditions&#x20;

This API endpoint supports the following Covata user [roles](/3.1/admin/administering-users.md#a-users-roles) (as described in the [Covata Platform Administrator's Guide](/3.1/admin.md)), conditions and [permissions](/3.1/api/access-service-api-v1-permissions-sets.md) (where applicable):

* [Originator](/3.1/admin/administering-users.md#originator-role) - a Covata user with this role can call the `GET`, `PUT` and `DELETE` methods on a collection they own.
* **Originator**, [Collaborator](/3.1/admin/administering-users.md#collaborator-role) and [Ad hoc](/3.1/admin/administering-users.md#adhoc-role) - a Covata user with any of these roles can call:

  * the `GET` method for a collection they are a collaborator on (with the **View** *permission*)
  * the **parentId** and **name** [parameters](/3.1/api/access-service-api-v1-collections-collectionid.md#access-service-api-v1-collections-collectionid-optional-parameters) of the `PUT` method for a collection they are a collaborator on (with the **Move** and **Rename** *permissions*, respectively) and
  * the `DELETE` method for a collection they are a collaborator on (with the **Remove (Folder)** *permission*).

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the [header](/3.1/api/access-service-api-v1-collections-collectionid.md#access-service-api-v1-collections-collectionid-required-headers) of requests to this endpoint.

## Required headers&#x20;

The appropriate access token as the `Bearer` token:

* `Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6`

The following header is required if the body of the request has a JSON object:

* `Content-Type: application/json`

## Optional parameters&#x20;

The following optional parameters can be sent in the body of the PUT request, each as individual members of a JSON object:

* **collaborators** - A parameter containing the following optional sub-element parameters, relating to the collaborators being applied to this collection:

  * **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 collection. (Although this sub-element is optional, omitting it serves no purpose.)
    * **permissionSet** - The [permission set](/3.1/api/access-service-api-v1-permissions-sets.md) to apply to this collaborator. This is done by specifying the ID of the permission set as a sub-element parameter of this parameter:

      * **id** - The ID of the permission set to apply to this collaborator. This ID can be obtained by calling the [\<access-service>/api/v1/permissions/sets](/3.1/api/access-service-api-v1-permissions-sets.md) API endpoint.

      **Note:** If this sub-element is omitted, then the **View** permission set is automatically applied to this collaborator.
  * **note** - A custom message to send as part of an email notification to collaborators (in the **list** above) once the request is sent.

  **Tip:** It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in an object) because [any modifications to one or more collaborators on an existing collection](/3.1/api/access-service-api-v1-collections-collectionid.md) requires all collaborators and their permission sets to be [specified in the collection modification request](/3.1/api/access-service-api-v1-collections-collectionid.md#access-service-api-v1-collections-collectionid-optional-parameters).
* **name** - .
* **parentId** - .

  **Example ():**

## Returns&#x20;

A JSON-formatted response containing the following members:

* **id** - .
* **name** - .
* **owner** - .

  * **email** - .
  * **firstName** - .
  * **lastName** - .
  * **id** - .
* **modifiedAt** - .
* **createdAt** - .
* **originator** - .

  * **email** - .
  * **userId** - .
* **shared** - .
* **parentId** - .
* **collaborators** - .

  * **email** - .
  * **firstName** - .
  * **lastName** - .
  * **id** - .
* **type** - .

  **Example (response from ...):**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.