Folder Resource

When authoring items in Surpass, you might find it useful to group items into folders and sub folders to improve the organisation of your items. Using the Surpass API, it is possible to search, filter these folders, return all the details on a specific folder and also create new folders.

Folder Resource

Below we have listed the operations, HTTP verbs and an example URL for the Folder resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/Folder/
Filter GET https://...surpass.com/api/v2/Folder?$filter=name eq ‘JamesTest’
Read (Individual by ID) GET https://...surpass.com/api/v2/Folder/1
Create POST https://...surpass.com/api/v2/Folder/
Update PUT https://...surpass.com/api/v2/Folder/1

Attributes for the Folder Resource

Within the table below we have provided all of the attributes included in the Folder resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET) Unique Identifier Mandatory for Create (POST)
Id Int The unique identifier for the folder. Unable to POST X X eq, lt, le, gt, ge, ne X N/A
Name string The name of the folder. X X eq, ne, contains X
Subject Resource The subject that the folder will belong to. ID or Ref can be supplied. Unable to PUT. X X eq, contains X
Parent folder id Int The ID of the parent folder. X X eq, lt, le, gt, ge, ne
Position Int Refers to the position of this folder within the parent folder.
GET Request and Return

The GET Folder resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the Folder resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page understanding the Surpass API.

Example GET request and response (JSON)
Example GET request and response (XML)


POST Request and Return

The POST Folder method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

Example POST request and response (JSON)
Example POST request and response (XML)

If "parentFolderId" is omitted this will be created in the root directory. Subject and Name are mandatory.

"position" refers to the position of the folder in the parent folder. If a number is supplied that is higher than the number of folders/items the folder will be placed last.

0 refers to the root directory when supplied in the parent folder id property and also indicates the first position when supplying the position property as part of the POST or PUT request.


PUT Request and Return

PUT Requests should reference the ID of the resource. The properties being updated should be included in the body of the request and can be sent in either JSON or XML format. All properties are optional within the PUT request so any omitted proprieties will be unchanged. The "Authorization" header will also be required in the request for it to be successful.

The body of the request should be formed in the same way as the POST request and the response also returns the same information. An example of this can be found in the “POST Request and Return” section above. The only differences between the POST and PUT requests is that the reference is required as part of the URL, all fields are optional and Subject cannot be supplied in the PUT request.


Required Permissions

To successfully call the Folder methods, the user specified in the header of the request must have the "Item Writer", “Item Reviewer” or “Item Publisher” role in Surpass.



Feedback and Knowledge Base