REST API for Content Management 1.1

Search Folders or Files

get

/documents/api/1.1/folders/search/items

Search for a folder or file by fulltext or querytext in the user's home directory.

This will search the entire directory tree under the home directory.

This will also search shared folders.

Request

Supported Media Types

application/json
application/xml

Query Parameters

fulltext

Type: string

Required: true

Search string used to match folders or files. It will search these locations: itemName, contents, extension, ownerName, lastModifiedName, and folderDescription.

Either fulltext or querytext must be provided in the search API.

limit

Type: string

Specify the maximum number of items to return. Use this parameter to specify how many items to include on a single page of results. The default is 50. The following example limits the number of returned items to 10:

limit=10

offset

Type: string

Specify the point at which to begin the list of items from the complete set of items returned for the action. If you do not specify an offset, the returned items begin with the first item in the item list (offset=0).

Use this parameter to specify the starting point for a given page of results from the complete set of returned items. The following example limits the number of items per page to 10 and displays the second page of results (items 11-20):

limit=10&offset=10

orderby

Type: string

Order the resulting items using the specified field and sort order. You can use the name, size, lastModifiedName, and lastModifiedDate fields, and a sort order of ascending (asc) or descending (desc). For example, this is the default:

orderby=name:asc

querytext

Type: string

Required: true

Search string used to match folders or files and allow for tag search or custom metadata field search as well. It can replace fulltext, taking advantage of string search, tag search, and custom metadata field search at the same time.

Either fulltext or querytext must be provided in the search API.

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Body

Root Schema : SearchFolderContents

Properties

count: Type: string

The number of items listed on the page.
errorCode: Type: string

An error code of zero (0) indicates no errors.
items: Type: array items

Additional Properties Allowed:

The files and subfolders in the home folder hierarchy.
offset: Type: string

The point at which to begin the list of items or page of results from the complete set.
totalCount: Type: string

Total number of items in the search.

Nested Schema : items

Type: array

The files and subfolders in the home folder hierarchy.

Items

Type: object

Title:

Additional Properties Allowed:

Minimum Number of Items: 0

Nested Schema :

Type: object

Title:

Minimum Number of Items: 0

Example application/json


{
    "count":"2",
    "errorCode":"0",
    "offset":"1",
    "totalCount":"3",
    "items":[
        {
            "type":"folder",
            "id":"FF4321BD2656077C897A0E701212FF6185DE5A6F9E67",
            "name":"three",
            "parentID":"self",
            "createdTime":"2015-12-09T20:51:53Z",
            "modifiedTime":"2015-12-09T20:51:53Z",
            "createdBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "ownedBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "modifiedBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "size":"-1"
        },
        {
            "type":"file",
            "id":"DB4C832D0F144C0DD6310F451212FF6185DE5A6F9E67",
            "name":"textData13.txt",
            "parentID":"F9363F588099E137C5B2939E1212FF6185DE5A6F9E67",
            "createdTime":"2015-12-07T23:19:13Z",
            "modifiedTime":"2015-12-07T23:19:13Z",
            "createdBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "ownedBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "modifiedBy":{
                "displayName":"Tenant1 UserA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "type":"user"
            },
            "size":"38",
            "version":"1"
        }
    ]
}

400 Response

Request parameters are not formatted correctly.

Examples

The following example searches for folders or files by fulltext in the user’s home directory. This search includes the entire directory tree under the home directory and shared folders.

GET .../folders/search/items?fulltext=three&orderby=size:asc&limit=2&offset=1

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "offset": "1",
    "totalCount": "3",
    "items": [
        {
            "type": "folder",
            "id": "FF4321BD2656077C897A0E701212FF6185DE5A6F9E67",
			"name": "three",
            "parentID": "self",
            "createdTime": "2015-12-09T20:51:53Z",
            "modifiedTime": "2015-12-09T20:51:53Z",
            "createdBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "-1"
        },
        {
            "type": "file",
            "id": "DB4C832D0F144C0DD6310F451212FF6185DE5A6F9E67",
            "name": "textData13.txt",
            "parentID": "F9363F588099E137C5B2939E1212FF6185DE5A6F9E67",
            "createdTime": "2015-12-07T23:19:13Z",
            "modifiedTime": "2015-12-07T23:19:13Z",
            "createdBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "38",
            "version": "1"
        }
    ]
}

Example 2

The following example searches for a folder or file using an invalid orderby sort field.

GET .../folders/search/items?fulltext=three&orderby=date

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "count": "0",
    "errorCode": "-96",
    "errorKey": "!csUnableToRetrieveSearchResults!csCloudOTSSearchInvalidSortField",
    "errorMessage": "Unable to retrieve search results. SortField is not valid.",
    "title": "Unable to retrieve search results. SortField is not valid.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 3

The following example searches for a folder or file using an invalid orderby sort order.

GET .../folders/search/items?fulltext=three&orderby=name:descending

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "count": "0",
    "errorCode": "-96",
    "errorKey": "!csUnableToRetrieveSearchResults!csSortOrderInvalid,descending",
    "errorMessage": "Unable to retrieve search results. Sort order 'descending' is invalid. Should be \"DESC\" or \"ASC\".",
}

Example 4

The following example searches for a folder or file with no fulltext search criteria.

GET .../folders/search/items

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "count": "0",
    "errorCode": "-97",
    "errorKey": "!csUnableToRetrieveSearchResults!csSearchMissingQueryText",
    "errorMessage": "Unable to retrieve search results. QueryText is missing.",
    "title": "Unable to retrieve search results. QueryText is missing.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 5

The following example searches for a folder or file with an invalid limit.

GET .../folders/search/items?fulltext=test&orderby=size:asc&limit=0

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "count": "0",
    "errorCode": "-1",
    "errorKey": "!csUnableToRetrieveSearchResults!csSearchItemNotPositive,ResultCount",
    "errorMessage": "Unable to retrieve search results. ResultCount must be greater than 0.",
    "title": "Unable to retrieve search results. ResultCount must be greater than 0.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 6

The following example searches for folders or files with a specific tag in the user's home directory. This search includes the entire directory tree under the home directory and shared folders. The tag value must be delimited by an encoded value of ` represented by %60.

GET .../folders/search/items?querytext=xtags<CONTAINS>%60personal%60

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "offset": "0",
    "totalCount": "2",
    "items": [
        {
            "type": "folder",
            "id": "FF4321BD2656077C897A0E701212FF6185DE5A6F9E67",
			"name": "three",
            "parentID": "self",
            "createdTime": "2015-12-09T20:51:53Z",
            "modifiedTime": "2015-12-09T20:51:53Z",
            "createdBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "-1"
        },
        {
            "type": "file",
            "id": "DB4C832D0F144C0DD6310F451212FF6185DE5A6F9E67",
            "name": "textData13.txt",
            "parentID": "F9363F588099E137C5B2939E1212FF6185DE5A6F9E67",
            "createdTime": "2015-12-07T23:19:13Z",
            "modifiedTime": "2015-12-07T23:19:13Z",
            "createdBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "38",
            "version": "1"
        }
    ]
}

Example 7

The following example searches for folders or files with a specific tag in the user's home directory, using text file search at the same time. This search includes the entire directory tree under the home directory and shared folders. The tag value must be delimited by an encoded value of ` represented by %60.

GET .../folders/search/items?querytext=xtags<CONTAINS>%60personal%60<AND><ftx>txt</ftx>

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "1",
    "errorCode": "0",
    "offset": "0",
    "totalCount": "1",
    "items": [
        {
            "type": "file",
            "id": "DB4C832D0F144C0DD6310F451212FF6185DE5A6F9E67",
            "name": "textData13.txt",
            "parentID": "F9363F588099E137C5B2939E1212FF6185DE5A6F9E67",
            "createdTime": "2015-12-07T23:19:13Z",
            "modifiedTime": "2015-12-07T23:19:13Z",
            "createdBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "Tenant1 UserA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "38",
            "version": "1"
        }
    ]
}

Example 8

The following example searches for folders or files with a specific metadata value in the user's home directory. This search includes the entire directory tree under the home directory and shared folders. The metadata value must be delimited by an encoded value of ` represented by %60.

GET .../folders/search/items?querytext=SearchableCollection.searchField1<CONTAINS>%60searchValue1%60

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "5",
    "errorCode": "0",
    "offset": "0",
    "totalCount": "5",
    "items": [
        {
            "type": "folder",
            "id": "F454F4DE5EF397E880FFA186B5D17B95F47087F4E518",
            "name": "subFolder",
            "parentID": "FECEAA81A82C83700E64B43EB5D17B95F47087F4E518",
            "createdTime": "2016-10-10T13:54:09Z",
            "modifiedTime": "2016-10-10T13:54:09Z",
            "createdBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "-1"
        },
        {
            "type": "file",
            "id": "D93A34CA721F82C77031708DB5D17B95F47087F4E518",
            "name": "file4.txt",
            "parentID": "FECEAA81A82C83700E64B43EB5D17B95F47087F4E518",
            "createdTime": "2016-09-21T14:08:54Z",
            "modifiedTime": "2016-09-21T14:08:54Z",
            "createdBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "25",
            "version": "1"
        },
        {
            "type": "file",
            "id": "DCDBEBB4803B7EE48E4B073AB5D17B95F47087F4E518",
            "name": "file3.txt",
            "parentID": "FECEAA81A82C83700E64B43EB5D17B95F47087F4E518",
            "createdTime": "2016-09-21T14:08:13Z",
            "modifiedTime": "2016-09-21T14:08:13Z",
            "createdBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "25",
            "version": "1"
        },
        {
            "type": "file",
            "id": "D8E8B2ABABAA0E42D3E4964CB5D17B95F47087F4E518",
            "name": "file2.txt",
            "parentID": "FECEAA81A82C83700E64B43EB5D17B95F47087F4E518",
            "createdTime": "2016-09-21T14:08:00Z",
            "modifiedTime": "2016-09-21T14:08:00Z",
            "createdBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "25",
            "version": "1"
        },
        {
            "type": "file",
            "id": "D1A21D80F7FDD74E9FD93695B5D17B95F47087F4E518",
            "name": "file1.txt",
            "parentID": "FECEAA81A82C83700E64B43EB5D17B95F47087F4E518",
            "createdTime": "2016-09-21T14:07:06Z",
            "modifiedTime": "2016-09-21T14:07:06Z",
            "createdBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "ownedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "size": "25",
            "version": "1"
        }
    ]
}