File resource

Get files list

OVERVIEW

This is the latest version of this API endpoint valid from Collaborate 4.1.4 and above, for older versions please see the child pages of this page

API method to get a list of files from Collaborate. The file list can be filtered using a search query. 

Request URI 

GET     /files

Parameters:

 

Parameter Name Type   Detail
limit int Optional No of items to returned
offset int Optional Starting point of the returned items. This should be the item ID.
ordertype String Optional can be one of name, size, author, lastModified, filetype
orderby string Optional  This is the order of the items returned. Possible values are "Asc" , "desc" , Default is Desc, which means that the latest items are returned first.
q string Mandatory query to filter out results, please check the search query details for specification of the "q" parameter

 

Search Query Parameters:

 The search query consists of three parts

  • Field  : field specifying the search criteria. e.g site
  • Operator : Test or condition that has to be performed on the data to create a filter
  • Value : The content of the attribute that is to be tested, e.g folderid = 217

The representation of q parameter works as under

q = "folderid=1"

Where q parameter is in double quotes and is URL encoded.

Additional q parameters supported from V2 of the API 
 

q parameter name Description
folderid=1 ID of the specific folder for which the file list is required
externalfileid={externalfileid}  If files are required for which an external file ID parameter has been provided when uploaded from an external DMS system. The external file id should have been supplied earlier using an API call. If the external file ID does not exist then the API call will return a 404 file not found error. (folderid is not required in this case, but if it is provided then the external file will be searched in the specific folder)
dmsdatabasename = {string DMS name} Name of the external database system (Used when externalfileid is provided) As an external file can be added multiple times to multiple locations, so if the request results in multiple files found in Collaborate then the client can also provide two optional parameters of dmsdatabasename and dmsparentfolderid. The client can provide either one or both of these parameters. 
dmsparentfolderid = {ID of the external parent folder of the DMS file} Parent folder id of the file (Used when externalfileid is provided)

 

Response XML

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
</files>
    <filetotal>Total no of files satisfying this search criteria</filetotal>
    <file>
        <name>RRRRRRRRRR</name>
        <id>868</id>
        <versionid>1</versionid>
        <createddate>20 Jun 2014 10:06</createddate>
        <modifieddate>20 Jun 2014 10:06</modifieddate>
        <auto-numbering>2.1.1</auto-numbering>   <!-- (Added in 4.1.3 ) -->
        <type>pdf</type>
        <size>775702</size>                      <!--(unit is in bytes) Supported from 4.0.3 branch -->
        <folderid>123</folderid>
        <siteid>234</siteid>
        <location>folder1/folder2</location>         <!-- support from 4.0.3 branch -->
        <icon>http://clientinstance.highq.com/clientinstance/images/fileicon/pdf.png</icon>
        <commentscount>0</commentscount>
        <likescount>0</likescount>
        <createdby>
            <firstname>Tom</firstname>
            <lastname>Chick</lastname>
            <email>user@highq.com</email>
            <userid>103</userid>
        </createdby>
        <modifiedby>
            <firstname>Tom</firstname>
            <lastname>Chick</lastname>
            <email>user@highq.com</email>
            <userid>103</userid>
        </modifiedby>
        <permission>
            <view>1</view>
            <edit>1</edit>                         <!-- support from 4.0.3 branch -->
            <delete>1</delete>
        </permission>
    </file>
</files>

 

Notes:

 

  • All dates are in UTC.
  • In this phase we are only supporting folderid in q parameter  
    • eg: q="folderid=12"
  • The default value for limit is 100
    • if limit>0 then (number of return data = limit)
    • if limit=-1 then return all data
    • if limit<-1 then default value of the limit will be returned, which is 100
  • The default value of offset is 0 
    • if offset>0 the starting point will be the offset value. 
    • if offset<0 then the default value of 0 will be used by the system
  • The default value of orderby parameter is descending (desc) 
  • The default value for ordertype parameter is creation date
  • <filetotal> element show total number of files contained in folder
  • "size" is returned depending on size configuration at site level, "size" is in Bytes.
  • Permissions, size and location parameter has been added to the response in Collaboarate 4.0.3
  • The permission element represents the callers permissions to the specific file. 
 
Code Meaning
200 Get File List successfully
400

Problem with parsing XML or JSON object (Bad Request)
401 Unauthorized
403 Validation failed/ Forbidden
405 Method not allowed (calling api with wrong method)
500 Internal error occurred

 

Comments


1 Comments


If I want to search for files across a site, rather than using this, is the correct way to have all your files linked to an iSheet from the beginning then search that? I noticed there was a file metadata iSheet, is that what that's for?

Last Updated: Jun 09,2023