> ## 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. # /api/v1/collections/{collectionId}/collections ## URL structure ```text theme={null} https://access-service.xy-company.com/api/v1/collections/{collectionId}/collections ``` where `{collectionId}` is the ID of a folder/collection. ## Supported methods and overview * `GET` - used to retrieve a list of information associated with all immediate child folders/[collections](/3.3/api/working-with-files-and-folders-fundamentals.md#collection) contained within the folder specified by `collectionId`. ## Detailed description This API endpoint retrieves a list of information about all immediate child folders contained within a folder specified by `collectionId`. * Folders retrieved in the [response](/3.3/api/access-service-api-v1-collections-collectionid-collections.md#access-service-api-v1-collections-collectionid-collections-returns) are those to which a given Covata user (whose [access token is submitted in the request](/3.3/api/access-service-api-v1-collections-collectionid-collections.md#access-service-api-v1-collections-collectionid-collections-supported-roles-and-conditions) to this endpoint) can access - i.e. as the owner of (or a collaborator on) the folder specified by `collectionId`. If this user is a collaborator on this folder, then only folders which this user is also a collaborator on are returned in the response. * Any folders contained within these immediate child folders are excluded in the response. \ **Tip:** To retrieve information about any folder nested within these child folders, make a subsequent request to this endpoint with the `collectionId` value being the ID of the relevant nested folder. A folder's ID can be obtained by calling the [\/api/v1/organisations/\{orgId}/items](/3.3/api/access-service-api-v1-organisations-orgid-items.md) API endpoint, which retrieves a list of information associated with folders that can be filtered using various 'search' criteria. The folders returned in a response to this API endpoint can be filtered according to those which: * Are present at the root level of a specific organization. * The Covata user (whose access token is submitted in the request) has permission to move an item (specified through the **movingItemId** [parameter](/3.3/api/access-service-api-v1-collections-collectionid-collections.md#access-service-api-v1-collections-collectionid-collections-optional-parameters) below). * The user (whose access token is submitted in the request) has permission to restore an item from the [Recycle Bin](/3.3/user/managing-secure-content.md#accessing-the-recycle-bin) (specified through the **itemToRestoreId** parameter below). ## Supported roles and conditions This API endpoint supports requests utilizing Covata user accounts with the following [roles](/3.3/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organization Administrator's Guide](/3.3/admin-org.md)): * [Originator](/3.3/admin-org/administering-users-within-an-organisation.md#originator-role) - when this user owns the folder whose ID is specified by `{collectionId}` in the request's URL. * **Originator**, [Collaborator](/3.3/admin-org/administering-users-within-an-organisation.md#collaborator-role) and [Ad hoc](/3.3/admin-org/administering-users-within-an-organisation.md#adhoc-role) - when this user is a collaborator on the folder whose ID is specified by `{collectionId}` in the URL. The Covata Platform's resources available to one of these Covata users (above) is determined by the access token submitted in the [header](/3.3/api/access-service-api-v1-collections-collectionid-collections.md#access-service-api-v1-collections-collectionid-collections-required-headers) of requests to this endpoint. ## Required headers The appropriate access token as the `Bearer` token: * `Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...` ## Optional parameters The following optional parameters can be sent in the **URL** of the GET request: * **organisationId** ( *Only applicable when the `collectionId` value is `0`, which represents the root level location.* ) - The ID of the organization from which items (i.e. folders at the root level location) will be retrieved. * **movingItemId** - The ID of an item (i.e. a file or folder) to restore to the folder/location (specified by `collectionId`). Specifying this parameter filters the response to folders which the Covata user (whose access token is submitted in the request) has permission to move this item. \ **Note:** This parameter cannot be specified in conjunction with **itemToRestoreId**. Doing so will cause the request to fail. * **itemToRestoreId** - The ID of an item currently located in the [Recycle Bin](/3.3/user/managing-secure-content.md#accessing-the-recycle-bin) to restore to the folder/location (specified by `collectionId`). Specifying this parameter filters the response to folders which the Covata user (whose access token is submitted in the request) has permission to restore this item. \ **Note:** This parameter cannot be specified in conjunction with **movingItemId**. Doing so will cause the request to fail. * **limit** - An integer value from `0` to `100`, representing the maximum number of items (i.e. folders) to be returned in the response from the Covata Platform, where an individual item is information about a folder. A value of `0` imposes no limit on the number of items returned. If this parameter is omitted, then its value is `10` by default. * **offset** - A value representing the count order of all retrievable items (i.e. folders) from the Covata Platform returned in the response. Since responses from this endpoint could amount to potentially unmanagable numbers of items being returned from the Covata Platform, this **offset** parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than `0` (i.e. the first item returned in a response). If this parameter is omitted, then its value is `0` by default. * **orderBy** - `ASC` or `DESC` (default is `ASC`). * **view** - Specify one of the following string values, which filters/retrieves only folders in the response according to the Covata user whose [access token is submitted in the request](/3.3/api/access-service-api-v1-collections-collectionid-collections.md#access-service-api-v1-collections-collectionid-collections-supported-roles-and-conditions) to this endpoint: * `owned-by-me` - retrieves only folders that this user currently owns. * `shared-with-me` - retrieves only folders that this user is a collaborator on (i.e. other people have shared these folders with this user). * `sharing` - retrieves only folders that this user has shared with other people. * `all` - retrieves all items that this user has access to. ## Returns 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 value of `collectionId` of the folder/location in the URL of this request. * **parentId** - The ID of the [folder/collection](/3.3/api/folder-handling-endpoints.md) that contains the folder specified by `collectionId`. A value of `0` indicates that this folder (specified by `collectionId`) is located at the logical root location. * **name** - The name of the folder specified by `collectionId`. * **createdAt** - The date and time when this folder was created. * **modifiedAt** - The date and time when this folder was last modified. When a folder is created (via the `POST` method on the [\/api/v1/organisations/\{orgId}/collections](/3.3/api/access-service-api-v1-organisations-orgid-collections.md) endpoint), this date and time should match (or be close to) that of the **createdAt** value below. Otherwise, if the folder has since been modified (e.g. via a `PUT` method request to this endpoint), this date and time should reflect when the folder was last modified. * **shared** - A boolean value that indicates whether or not the folder has been shared with any collaborators. \ **Note:** If the request was made using the access token of an authenticated collaborator user (without the **View Other** [permission](/3.3/api/access-service-api-v1-permissions-sets.md)) on the file object, then the value returned will be `false`. * **originator** - A member containing information about the Covata user whose account was used to create this folder. This member contains the equivalent **email** and **id** sub-members only of either the **owner** member (above) or a **collaborators** array element (below). If these sub-members originally match those of the folder's initial **owner** member and then the folder's ownership changes to that of another Covata user, the **owner** member's **email** and **id** values will change while the equivalent sub-member values of this **originator** member will remain unchanged. * **owner** - A member containing information about the Covata user who is the current owner of the folder. This member contains the following sub-members: * **id** - The ID of this Covata user's account. * **email** - The email address of the Covata user who owns this folder. * **firstName** - The first name set by this Covata user. * **lastName** - The last name set by this Covata user. * **permissions** - An array listing the individual [permissions](/3.3/api/access-service-api-v1-permissions-sets.md) that the **owner** above or a collaborator on (whose access token was used in the request to this endpoint), has inherited from the location represented by **parentId**. * **organisationId** - The ID of the organization that contains this folder. * **count** - The total number of items (i.e. collections) below, returned in the response. * **offset** - The value of the **offset** which had been used in the request to this endpoint. * **items** - An array containing information about the folders (which are immediate children of `collectionId`), returned in the response to this endpoint. Each element of this array contains information about one of these folders, represented as an object containing all of the members above (except **originator**, **count**, **offset** and **items**) as well as the following members. * **parentName** - The name of the parent folder. Currently, this value is always `null`. * **type** - Should be `collection`, indicating that the type of item returned is a folder. * **organisation** - A member containing information about the organization that contains this folder. This member contains the following sub-members: * **name** - The name of the organization. * **description** - The organization's description (if this has been set). * **id** - The ID of the organization. **Example (response):** ```json theme={null} { "id": "751980834491527168", "parentId": "0", "name": "Large Files", "createdAt": "2016-09-06T01:43:22.071Z", "modifiedAt": "2016-09-07T04:49:05.719Z", "shared": true, "originator": { "id": "749419842687528960", "email": "alex.originator@xy-company.com" }, "owner": { "id": "749419842687528960", "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator" }, "permissions": [{ "id": "66", "nameI18nCode": "server.permission.name.file.delete" }, { "id": "67", "nameI18nCode": "server.permission.name.folder.delete" }, { "id": "62", "nameI18nCode": "server.permission.name.download" }, { "id": "69", "nameI18nCode": "server.permission.name.move" }, { "id": "60", "nameI18nCode": "server.permission.name.view" }, { "id": "72", "nameI18nCode": "server.permission.name.delete.other" }, { "id": "63", "nameI18nCode": "server.permission.name.copy" }, { "id": "61", "nameI18nCode": "server.permission.name.print" }, { "id": "73", "nameI18nCode": "server.permission.name.share" }, { "id": "68", "nameI18nCode": "server.permission.name.rename" }, { "id": "71", "nameI18nCode": "server.permission.name.view.other" }, { "id": "65", "nameI18nCode": "server.permission.name.folder.create" }, { "id": "64", "nameI18nCode": "server.permission.name.file.upload" }], "organisationId": "749418071827214336", "count": "2", "offset": "0", "items": [{ "id": "752389961810243584", "name": "Another", "parentId": "751980834491527168", "parentName": null, "createdAt": "2016-09-07T04:49:05.625Z", "modifiedAt": "2016-09-07T04:49:05.841Z", "type": "collection", "shared": true, "owner": { "id": "749419842687528960", "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator" }, "permissions": [{ "id": "66", "nameI18nCode": "server.permission.name.file.delete" }, { "id": "67", "nameI18nCode": "server.permission.name.folder.delete" }, { "id": "62", "nameI18nCode": "server.permission.name.download" }, { "id": "69", "nameI18nCode": "server.permission.name.move" }, { "id": "60", "nameI18nCode": "server.permission.name.view" }, { "id": "72", "nameI18nCode": "server.permission.name.delete.other" }, { "id": "63", "nameI18nCode": "server.permission.name.copy" }, { "id": "61", "nameI18nCode": "server.permission.name.print" }, { "id": "73", "nameI18nCode": "server.permission.name.share" }, { "id": "68", "nameI18nCode": "server.permission.name.rename" }, { "id": "71", "nameI18nCode": "server.permission.name.view.other" }, { "id": "65", "nameI18nCode": "server.permission.name.folder.create" }, { "id": "64", "nameI18nCode": "server.permission.name.file.upload" }], "organisation": { "name": "XY Company", "description": "", "id": "749418071827214336" } }, { "id": "752389806390308864", "name": "Secret", "parentId": "751980834491527168", "parentName": null, "createdAt": "2016-09-07T04:48:28.570Z", "modifiedAt": "2016-09-07T04:48:28.656Z", "type": "collection", "shared": true, "owner": { "id": "749419842687528960", "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator" }, "permissions": [{ "id": "66", "nameI18nCode": "server.permission.name.file.delete" }, { "id": "67", "nameI18nCode": "server.permission.name.folder.delete" }, { "id": "62", "nameI18nCode": "server.permission.name.download" }, { "id": "69", "nameI18nCode": "server.permission.name.move" }, { "id": "60", "nameI18nCode": "server.permission.name.view" }, { "id": "72", "nameI18nCode": "server.permission.name.delete.other" }, { "id": "63", "nameI18nCode": "server.permission.name.copy" }, { "id": "61", "nameI18nCode": "server.permission.name.print" }, { "id": "73", "nameI18nCode": "server.permission.name.share" }, { "id": "68", "nameI18nCode": "server.permission.name.rename" }, { "id": "71", "nameI18nCode": "server.permission.name.view.other" }, { "id": "65", "nameI18nCode": "server.permission.name.folder.create" }, { "id": "64", "nameI18nCode": "server.permission.name.file.upload" }], "organisation": { "name": "XY Company", "description": "", "id": "749418071827214336" } }] } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.