> ## 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.

# Retrieving information about items from the Covata Platform

The Covata API's interaction with specific [Secure Objects](/3.0/api/creating-secure-objects-and-collections.md#secure-object) and [collections](/3.0/api/creating-secure-objects-and-collections.md#collection) relies heavily on submitting requests to the API using the ID values of these [items](/3.0/api/creating-secure-objects-and-collections.md#item).

If your application does not store these items' IDs, information about a specific subset of items can be retrieved (as a list) by filtering all items recorded on the Covata Platform using navigable or memorable criteria, such as a 'search' substring that matches part of an item's name, or email address, first name or last name of the item's owner. From this manageable list of items retrieved from the Covata Platform, the required items' IDs can be obtained.

This page describes how to use Covata's API to retrieve a list of information about:

* [All immediate items of a common parent](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-immediate-items-of-a-common-parent),
* [All items filtered by text search](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-items-filtered-by-text-search) (i.e. items whose name or owner's email address/first name/last name contains a specified string),
* [All items based on ownership or sharing status](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-items-based-on-ownership-or-sharing-status) (where 'sharing status' refers to items that a Covata user either has shared or is a collaborator on) and
* [All ancestral collections of an item](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-ancestral-collections-of-an-item).

This page also describes how to [sort, order and paginate](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#sorting-ordering-and-paginating-the-list-of-item-info) any list of items retrieved using these procedures.

> [!NOTE]
>
> * Before retrieving a list of [Secure Objects](/3.0/api/creating-secure-objects-and-collections.md#secure-object) and [collections](/3.0/api/creating-secure-objects-and-collections.md#collection), your application must have a valid access token obtained by authenticating and authorizing a Covata user to the Covata Platform, where this user either:
>
>   * has the appropriate [role](/3.0/admin/administering-users.md#a-users-roles) to create their own items (i.e. the [Originator role](/3.0/admin/administering-users.md#originator-role)) or
>   * be a *collaborator* on items which other users have shared with them. For more information about the definition of a collaborator and sharing items, see [Sharing items](/3.0/api/sharing-items.md).
>
>   For more information about authenticating and authorizing Covata users to the Covata Platform, see [Authorizing your application](/3.0/api/authentication-and-authorization.md#authorizing-your-application) on the [Authentication and authorization](/3.0/api/authentication-and-authorization.md) page of this guide and the [Configuring client applications](/3.0/admin/configuring-client-applications.md) page of the [Covata Platform Administrator's Guide](/3.0/admin.md).
> * The **Supported roles (and permissions)** sections of each API endpoint page (linked to from the procedures below) contain details about the roles and permissions that a Covata user requires for a successful request to the endpoint (along with a valid access token representing this user).

## Retrieving info about all immediate items of a common parent

Information about immediate child items (i.e. both Secure Objects and collections) of a common parent can be retrieved as a list from the Covata Platform. This common parent can be either a parent collection of these child items, or the logical root level.

To retrieve a list of information about all immediate child items of a common parent, make a `GET` request to the [\<access-service>/api/v1/items](/3.0/api/access-service-api-v1-items.md) API endpoint with the **collectionId** URL parameter whose value is either:

* the parent collection's ID (i.e. of the collection that contains these child items), or
* `0` to specify items located at the logical root level.

## Retrieving info about all items filtered by text search

Information about all items whose name or owner's email address/first name/last name contains a specified string, irrespective of an item's location or ownership, can be retrieved as a list from the Covata Platform. (This is effectively a text search feature.)

To retrieve a list of information about all items whose name or owner's email address/first name/last name contains a specified string, make a `GET` request to the [\<access-service>/api/v1/items](/3.0/api/access-service-api-v1-items.md) API endpoint with the **searchText** URL parameter whose value contains the specified string itself.

> [!NOTE]
>
> It is not possible to specify both the **searchText** and [collectionId](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-immediate-items-of-a-common-parent) (above) URL parameters in the same request.

## Retrieving info about all items based on ownership or sharing status&#x20;

Information about all items belonging to a Covata user (represented by an access token), or all items which this user has shared or is a collaborator on (i.e. the items' sharing status in relation to the user) can be retrieved as a list from the Covata Platform.

To retrieve this list of information about all items:

* belonging to a Covata user or
* based on their sharing status in relation to this user,

make a `GET` request to the [\<access-service>/api/v1/items](/3.0/api/access-service-api-v1-items.md) API endpoint and specifying the **view** URL parameter with a value of:

* `owned-by-me` to retrieve all items owned by the specified Covata user<sup>\*</sup>,
* `shared-with-me` to retrieve all items that other Covata users have shared with the specified Covata user<sup>\*</sup>,
* `sharing` to retrieve all items that the specified Covata user<sup>\*</sup> has shared with other people, or
* `all` to retrieve all items that the specified Covata user<sup>\*</sup> can access.

<sup>\*</sup> In each case, the specified Covata user is represented by its valid access token passed in the header of the request.

> [!TIP]
>
> The **view** URL parameter can be used in conjunction with both the [collectionId](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-immediate-items-of-a-common-parent) and [searchText](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-items-filtered-by-text-search) parameters (above) for additional filtering.

## Retrieving info about all ancestral collections of an item

To retrieve information about all ancestral collections (back to the logical root level) of an item, make a `GET` request to the [\<access-service>/api/v1/items/\{itemId}/ancestry](/3.0/api/access-service-api-v1-items-itemid-ancestry.md) API endpoint.

All ancestral collections from the logical root level through to the parent collection of item whose ID is specified in this request's URL is returned in the response. The response is a flat list of information about these ancestral collections in hierarchical order from the logical root level.

## Sorting, ordering and paginating the list of item info

The list of information about all retrieved items [from a common parent](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-immediate-items-of-a-common-parent), [filtered by text search](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-all-items-filtered-by-text-search) or [based on ownership or sharing status](/3.0/api/retrieving-information-about-items-from-the-covata-platform.md#retrieving-info-about-items-based-on-ownership-or-sharing-status) can be sorted, ordered and paginated by specifying the following additional URL parameters in the appropriate `GET` request to the [\<access-service>/api/v1/items](/3.0/api/access-service-api-v1-items.md) API endpoint:

* **sortBy** - The item's field by which the items in the list is ordered. Valid values are:

  * `NAME` - the item's name (which is the default value if this parameter is omitted),
  * `OWNER` - the item's owner,
  * `MODIFIED` - the date when the item was last modified, or
  * `CREATED` - the date when the item was created.
* **orderBy** - The **sortBy** field is ordered by the value of this field. Valid values are:

  * `ASC` - for ascending alphanumeric or chronological order (which is the default value if this parameter is omitted), or
  * `DESC` - for descending alphanumeric or chronological order.
* **limit** - The maximum number of items returned in the response. If this parameter is omitted, its value is `10` by default.
* **offset** - The count order of all retrievable items from the Covata Platform filtered using other URL parameters in the request. If this parameter is omitted, its value is `0` by default.

For more information about the **limit** and **offset** URL parameters for paginating items returned in the response, refer to the descriptions of these parameters in the [Optional parameters](/3.0/api/access-service-api-v1-items.md#access-service-api-v1-items-optional-parameters) section on the [\<access-service>/api/v1/items](/3.0/api/access-service-api-v1-items.md) page.


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