> ## 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/items/{itemId}/ancestry

## URL structure&#x20;

```text theme={null}
https://access-service.xy-company.com/api/v1/items/{itemId}/ancestry
```

where `{itemId}` is the ID of a file object/Secure Object or folder/collection.

## Supported methods and overview&#x20;

* `GET` - retrieves a list of information about the ancestral folders/[collection](/3.5/api/working-with-files-and-folders-fundamentals.md#collection)s of a specified file object/[Secure Object](/3.5/api/working-with-files-and-folders-fundamentals.md#secure-object) or folder (i.e. [item](/3.5/api/working-with-files-and-folders-fundamentals.md#item)), specified by `itemId`.

> [!NOTE]
>
> This method takes no parameters.

## Detailed description&#x20;

This API endpoint retrieves a list of information about the ancestral folders of a file object or folder, specified by `itemId`.

The item's ID can be obtained by calling the [\<access-service>/api/v1/organisations/\{orgId}/items](/3.5/api/access-service-api-v1-organisations-orgid-items.md) API endpoint, which retrieves a list of information associated with file objects and folders that can be filtered using various 'search' criteria.

The list of folder information returned is ordered from the root location (whose ID is `0`) first, through to the immediate parent folder last.

## Supported roles and conditions&#x20;

This API endpoint supports requests utilising Covata user accounts with the following [roles](/3.5/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organisation Administrator's Guide](/3.5/admin-org.md)):

* [Originator](/3.5/admin-org/administering-users-within-an-organisation.md#originator-role) - when this user owns the item whose ID is specified by `{itemId}` in the request's URL.
* **Originator**, [Collaborator](/3.5/admin-org/administering-users-within-an-organisation.md#collaborator-role) and [Ad hoc](/3.5/admin-org/administering-users-within-an-organisation.md#adhoc-role) - when this user is a collaborator on the item whose ID is specified by `{itemId}` 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.5/api/access-service-api-v1-items-itemid-ancestry.md#access-service-api-v1-items-itemid-ancestry-required-headers) of requests to this endpoint.

## Required headers&#x20;

The appropriate access token as the `Bearer` token:

* `Authorisation: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...`

## Returns&#x20;

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

For successful requests only, a JSON-formatted response containing an array of objects with the following members is also returned:

* **id** - The ID of the location/folder represented by this JSON object. For the root location, this value is `0`. For a folder location, this value is the folder's ID.
* **name** - The name of the folder represented by this JSON object. For the root location, this value is an empty string. For a folder location, this value is the folder's name.
* **parentId** - The ID of the parent location of the folder represented by this JSON object. For the root location, this value is `0`. For a folder location, this value is the immediate parent folder's ID (or `0` if the immediate parent location is the root location). \

  **Example (response):**

  ```json theme={null}
  [{
      "id": "0",
      "name": "",
      "parentId": "0"
  }, {
      "id": "751980834491527168",
      "name": "Shared Folder",
      "parentId": "0"
  }, {
      "id": "752389961810243584",
      "name": "Other",
      "parentId": "751980834491527168"
  }]
  ```


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