Skip to main content
The Covata API’s interaction with specific files and folders relies heavily on submitting requests to the API using the ID values of these items. If your application does not store these items’ IDs, information about a specific subset of all items recorded on the Covata Platform (matching specific/memorable criteria and scoped within a specific organisation to which the items belong) can be retrieved as a list. Such criteria could be a ‘search’ substring that matches a property of the item, such as the name of the item or its owner’s name, or an enum value defining the sharing/ownership status of the item. From this manageable list of items retrieved from an organisation, the required items’ IDs can be obtained. This page describes how to use the Covata API to retrieve a list of information about: This page also describes how to sort, order and paginate any list of items retrieved using these procedures.
  • Before retrieving a list of files and folders, your application must have a valid access token obtained by authenticating and authorising a Covata user to the Covata Platform, where this user is either: Also, for more information about authenticating and authorising Covata users to the Covata Platform, see Initiating authentication and authorisation on the Authentication and authorisation page of this guide and the Configuring client applications page of the SafeShare Administrator’s Guide.
  • The Supported roles (and conditions) section of each API endpoint page (accessible from the relevant procedures throughout this Developer’s Guide) contains details about the roles a Covata user requires and the conditions they must meet, for requests to these endpoints (which would include a valid access token representing the user’s authenticated session) to succeed.

​
Retrieving info about all immediate items of a common parent

Information about immediate child items (i.e. both files and folders) of a common parent can be retrieved as a list from the Covata Platform. This common parent can be either a parent folder of these child items, or the logical root level. To retrieve this list of information about all immediate child items of a common parent, make a GET method request to this API endpoint: with the collectionId URL parameter whose value is either:
  • the parent folder’s ID (i.e. of the folder that contains these child items), or
  • 0 to specify items located at the logical root level.
The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved. If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

​
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 method request to the following API endpoint: with the searchText URL parameter whose value contains the specified string itself. Be aware that it is not possible to specify both the searchText and collectionId (above) URL parameters in the same request. The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved. If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

​
Retrieving info about items based on ownership or sharing status

For a given organisation, the Covata Platform can retrieve a list of information about all items at a given location which:
  • belong to a Covata user (represented by an access token),
  • this user is a collaborator on,
  • this user has access to,
OR information about every item which this user has shared. To retrieve this list of information about items based on these criteria, make a GET method request to the following API endpoint: and specify the view URL parameter with an enum value of:
  • owned-by-me to retrieve all items owned by a given Covata user * ,
  • shared-with-me to retrieve all items that other Covata users have shared with a given Covata user * ,
  • sharing to retrieve all items that a given Covata user * has shared with other people, or
  • all to retrieve all items that a given Covata user * can access.
The view URL parameter can be used in conjunction with both the collectionId and searchText parameters (above) for additional filtering.
* In each case, this Covata user is determined by a valid access token (representing this user) passed in the header of the request. The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved. If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

​
Retrieving info about all ancestral collections of an item

To retrieve information about all ancestral folders (back to the logical root level) of an item, make a GET method request to the following API endpoint: The value of {itemId} in the URL path of the request is the ID of the file or folder from which all ancestral folders (through to the logical root level) will be retrieved in the response. If the request was successful, a JSON object is returned in the response containing a single array of elements, where each element contains information about an ancestral folder (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, filtered by text search or based on ownership or sharing status can be sorted, ordered and paginated (when making a GET method request to the following API endpoint): by specifying the following additional URL parameters:
  • sortBy - The item’s field by which the items in the list is ordered. Valid enum values for this parameter 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 enum values for this parameter 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, see Optional parameters (of <access-service>/api/v1/organisations/{orgId}/items). If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.