Search Folders or Files
/documents/api/1.2/folders/search/items
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. The search has a limit of 10000 items (folders and files).Request
- application/json
- application/xml
-
fields(optional): string
Specify the additional fields to be returned. Currently, the only value supported is
metadata
, which would result in metadata associated with items returned by the search results being added to the response. The default is not to return metadata in the search results. In order to have metadata returned, usefields=metadata
-
fulltext: string
Search string used to match folders or files. It will search these locations:
itemName
,contents
,extension
,ownerName
,lastModifiedName
, andfolderDescription
.Either
fulltext
orquerytext
must be provided in the search API. -
limit(optional): 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
20
and maximum is10000
. The following example limits the number of returned items to 10:limit=10
-
offset(optional): 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(optional): string
Order the resulting items using the specified field and sort order. You can use the
name
,size
,lastModifiedName
, andlastModifiedDate
fields, and a sort order of ascending (asc
) or descending (desc
). For example, this is the default:orderby=name:asc
-
querytext: string
Search string used to search for folders or files using the targets listed below. It can replace
fulltext
, taking advantage of multiple targets at the same time.Either the
fulltext
orquerytext
parameter must be provided in the search API.The
querytext
parameter can target searches against the following string fields or number field. The search query is in the form:searchField<operation>searchValue
Multiple searches can be combined with <AND> and <OR>. Searches are not case-sensitive.
The following string fields are supported:- xTags: search for tags
- fItemType: search by item type, either
File
to return only file items orFolder
to return only folder items. - fItemName: search for an item's name.
In the response this is thename
field. - fCreator: search by the ID of the item's creator.
In the response this is thecreatedBy.id
field. - fCreatorFullName: search by the full display name of the item's creator.
In the response this is thecreatedBy.displayName
field. - fCreatorLoginName: search by the login name of the item's creator.
In the response this is thecreatedBy.loginName
field. - fOwner: search by the ID of the item's owner.
In the response this is theownedBy.id
field. - fOwnerFullName: search by the full display name of the item's owner.
In the response this is theownedBy.displayName
field. - fOwnerLoginName: search by the login name of the item's owner.
In the response this is theownedBy.loginName
field. - fLastModifier: search by the ID of the user to last modify the item.
In the response this is themodifiedBy.id
field. - fLastModifierFullName: search by the full display name of the user to last modify the item.
In the response this is themodifiedBy.displayName
field. - fLastModifierLoginName: search by the login name of the user to last modify the item.
In the response this is themodifiedBy.loginName
field. - Searchable metadata fields can also be searched as string search targets, but metadata field values are not returned by the search. When you search by metadata fields, the target is
MetadataCollectionName.metadataFieldName
. For more information about metadata, see Metadata Collection REST Endpoints
The string search supports
<CONTAINS>
and<MATCHES>
operations.<CONTAINS>
operator instructs search to look for text fields being searched to contain specified "words". The words must be separated by tokens like whitespace and periods.<MATCHES>
operator instructs search to look for an exact (albeit, case-insensitive) match of the field value, including whitespaces and periods.
The following date fields are supported:- fCreateDate: search by the created timestamp. Should be in the
yyyy-mm-ddThh:mm:ssZ
format, e.g.2020-03-25T10:10:10Z
.
In the response this is thecreatedTime
field. - fLastModifiedDate: search by the last modified timestamp. Should be in the
yyyy-mm-ddThh:mm:ssZ
format, e.g.2020-03-25T10:10:10Z
.
In the response this is themodifiedTime
field. - Searchable metadata fields can also be searched as date search targets, but metadata field values are not returned by the search. When you search by metadata fields, the target is
MetadataCollectionName.metadataFieldName
. For more information about metadata, see Metadata Collection REST Endpoints
The following number field is supported:- dSize: search by the size in bytes of an item.
The number and date search targets support the following operations.
- Use < to search for values less that the search value.
- Use = to search for values equal to the search value.
- Use > to search for values greater than the search value.
- Use <= to search for values less than or equal to the search value.
- Use >= to search for values greater than or equal to the search value.
Response
- application/json
- application/xml
200 Response
The request was fulfilled.
object
-
count(optional):
string
The number of items listed on the page.
-
errorCode(optional):
string
An error code of zero (0) indicates no errors.
-
items(optional):
array items
The folders and files returned by the search.
-
offset(optional):
string
The point at which to begin the list of items or page of results from the complete set.
-
totalCount(optional):
string
Total number of items in the search.
array
-
Array of:
object FileAndSubFoldersItemsDefinition
The files and subfolders in the folder.
object
-
childItemsCount(optional):
string
Number of items contained in the folder.
-
createdBy(optional):
object User
User information
-
createdTime(optional):
string
Folder or file creation date.
-
id(optional):
string
Globally unique identifier (GUID) for the folder or file.
-
modifiedBy(optional):
object User
User information
-
modifiedTime(optional):
string
Folder or file last modified date.
-
name(optional):
string
Folder or file name.
-
ownedBy(optional):
object User
User information
-
parentID(optional):
string
Globally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for
parentID
isself
. -
size(optional):
string
If the item is a file, the size of the file in bytes. If the item is a folder, then the size of the folder including all of the files and sub folders contained in the folder.
-
type(optional):
string
Item type, either
folder
orfile
. -
version(optional):
string
If the item is a file, the number of versions of the file.
object
-
displayName(optional):
string
The display name for the user.
-
id(optional):
string
Globally unique identifier (GUID) for the user.
-
loginName(optional):
string
The login name for the user.
-
type(optional):
string
Item type
user
.
{
"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":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"ownedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"modifiedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"metadata":{
"items":[
{
"name":"MyMetaCollection",
"fields":{
"items":[
{
"name":"IntField",
"type":"integer",
"value":"12345"
},
{
"name":"DateField",
"type":"date",
"value":"2023-02-20T12:00:00.000Z"
}
]
}
},
{
"name":"dDefaultFolderMetaCollection",
"fields":{
"items":[
{
"name":"xTags",
"type":"string",
"value":"FixMe"
}
]
}
}
]
},
"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":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"ownedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"modifiedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"metadata":{
"items":[
]
},
"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": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "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": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "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": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "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": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "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": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "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", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "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", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "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", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "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", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "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", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "size": "25", "version": "1" } ] }