Search API

Introduction

If you need to search for files, then you can use the WebDAV search API. The search API exposes two endpoints for finding files in a user’s filesystem.

Search Files

The search-files report search through the available files in an ownCloud user’s filesystem, based on a rudimentary filename pattern match.

By default, the report uses ownCloud’s default search provider to power the search functionality. However, other search providers, such as search_elastic and search_lucene greatly enrich the ability to search, such as being able to search through file content, as well as by a file’s name. When installed, they replace ownCloud’s default search provider and the search API will automatically use them.

When using the default search provider, if you use the search string "ownCloud", files whose filename has "ownCloud" in it will be matched. However, if installed the search_elastic app, the report also retrieves files that have "ownCloud" in the file’s contents.

Core Details

Request Path Method Content Type

remote.php/dav/files/<user>

REPORT

text/xml

The Request

An authenticated REPORT request needs to be made to search for all files stored in a user’s ownCloud filesystem

Example Request

curl --silent \
  -X REPORT \
  --data "@supported.xml" \
  -u admin:admin \
  'http://localhost/remote.php/dav/files/admin' | xmllint --format -

The request must include a request body that includes the search pattern, and can also include a list of properties to return.

Example Request Bodies

Below, are several examples of XML response bodies.

Searching For Records

In the search element, specify the search pattern to filter the list of files to return.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files 
    xmlns:a="DAV:" 
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <oc:pattern>web</oc:pattern>
    </oc:search>
</oc:search-files>
Filtering Records

The filter-rules element provides the ability to filter records based on a range of properties. In the example below, you can see how to filter out any file that has not been favorited.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files 
    xmlns:a="DAV:" 
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <oc:pattern>web</oc:pattern>
    </oc:search>
</oc:search-files>
Limiting The Number Of Results Returned

To limit the number of results returned, use a combination of the search element’s limit, and offset elements, as in the following example. In the example below, at most one hundred records, starting from record 200, will be returned.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files 
    xmlns:a="DAV:" 
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <!-- The number of results to retrieve -->
        <oc:limit>100</oc:limit>
        <!-- The offset to retrieve (here, 200 would be indicate the second page) -->
        <oc:offset>200</oc:offset>
    </oc:search>
</oc:search-files>
Reducing The File Properties Returned

However, if a specific list of properties is required for each file, then a prop element needs to be included in the response body, such as in the example below.

Table 1. Available File Properties
Property Description Namespace

getcontentlength

The file’s content length. This is only sent for files, not for folders and collections. Refer to the size property for folders and collections.

DAV

getcontenttype

The file’s content type.

DAV

getetag

The file’s ETag

DAV

getlastmodified

The last modified date of the file

DAV

lockdiscovery

Supports the "persistent file locking" backend feature. For more information on this property, please refer to the W3C spec.

DAV

resourcetype

The resource’s type. If the resource is a folder, then the value is set to collection, otherwise, no value is returned.

DAV

comments-unread

The number of comments on the item that have yet to be read.

http://owncloud.org/ns

favorite

Indicates whether the file has been favorited or not

http://owncloud.org/ns

fileid

The id of the file

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

share-types

It is an OC-specific property which summarizes what outgoing share types are applied to the current item. The share type values are:

  • 0: user share

  • 1: group share

  • 3: link shares

http://owncloud.org/ns

size

The size of a folder or collection. This property is not returned for files. Refer to the getcontentlength property for folders and collections.

http://owncloud.org/ns

tags

A collection of tags that have been added to the file.

http://owncloud.org/ns

 
<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files 
    xmlns:a="DAV:" 
    xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <a:getcontentlength />
        <a:getcontenttype />
        <a:getetag />
        <a:getlastmodified />
        <a:lockdiscovery />
        <a:resourcetype />
        <oc:comments-unread />
        <oc:favorites />
        <oc:fileid />
        <oc:owner-display-name />
        <oc:permissions />
        <oc:share-types />
        <oc:size />
        <oc:tags />
    </a:prop>
    <oc:search>
        <oc:pattern>site</oc:pattern>
    </oc:search>
</oc:search-files>
The example uses xmllint to make the response more readable. Xmllint is available in the libxml2 package.

The Response

Success

Successful requests return two things:

  1. An XML payload.

  2. A status of HTTP/1.1 207 Multi-Status.

You can see an example of the XML payload below. The XML payload contains a response element for each file. And each response element contains three items:

  1. A link to the file (href).

  2. The requested properties, along with their respective values (propstat).

  3. The file’s status (status).

Search Response
<?xml version="1.0"?>
<d:multistatus 
    xmlns:d="DAV:" 
    xmlns:s="http://sabredav.org/ns" 
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/files/admin/Test/Sub-test/Site-Plan.md</d:href>
    <d:propstat>
      <d:prop>
        <oc:id>00000065oc21s4c9iej2</oc:id>
        <oc:downloadURL/>
        <oc:fileid>65</oc:fileid>
        <oc:permissions>RDNVW</oc:permissions>
        <oc:size>423</oc:size>
        <oc:owner-id>admin</oc:owner-id>
        <oc:owner-display-name>admin</oc:owner-display-name>
        <d:getlastmodified>Fri, 28 Jul 2017 05:51:07 GMT</d:getlastmodified>
        <d:getetag>"0286fcdabf5b4f5ef84788d86c37e245"</d:getetag>
        <d:getcontenttype>text/markdown</d:getcontenttype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

Failure

If The Payload File Cannot Be Read Or Is Invalid XML

If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an HTTP/1.1 500 Internal Server Error status code.

<?xml version="1.0" encoding="utf-8"?>
<d:error 
    xmlns:d="DAV:" 
    xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\Xml\ParseException</s:exception>
  <s:message>This should never happen (famous last words)</s:message>
</d:error>
If a Non-Existent Property Is Requested

If a non-existent property is requested, then an additional propstat element is returned, as in the example below, which contains a list of the properties which were not available.

  <d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
  <d:prop>
    <oc:downloadUR/>
  </d:prop>
  <d:status>HTTP/1.1 404 Not Found</d:status>

Filter Files

The filter-files report allows for retrieving a list of files in an ownCloud user’s filesystem, based on two criteria:

Core Details

Request Path Method Content Type

remote.php/dav/files/<user>

REPORT

text/xml

The Request

An authenticated REPORT request needs to be made to retrieve a list of all files stored in a user’s ownCloud filesystem.

Example Request

curl --silent \
  -X REPORT \
  --data "@filter-files-criteria.xml" \
  -u admin:admin \
  'http://localhost/remote.php/dav/files/admin' | xmllint --format -

The request must include a request body that includes the rules to filter by. There are two filter rules which can be supplied; these are:

Rule Description Type Accepted Values Mandatory

favorite

Whether they’ve been marked as a favorite or not (mandatory)

integer

0,1

Yes

systemtag

The tags that have been assigned to them

integer

Any valid system tag. These can be retrieved by using the Tags API.

No

Example Request Bodies

Below, are several examples of the XML response bodies that can be sent with the request.

Minimal Request Body

In the search element, it specifies the search pattern to filter down the list of files to return in a successful resultset.

<?xml version="1.0" encoding="UTF-8"?>
<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
    <oc:filter-rules>
        <oc:favorite>1</oc:favorite>
    </oc:filter-rules>
</oc:filter-files>
Limiting Returned File Properties

If only a specific list of properties is required for each file, then a prop element needs to be included in the response body, such as in the example below.

Table 2. Available File Properties
Property Description Namespace

getcontentlength

The file’s content length. This is only sent for files, not for folders and collections. Refer to the size property for folders and collections.

DAV

getcontenttype

The file’s content type.

DAV

getetag

The file’s ETag

DAV

getlastmodified

The last modified date of the file

DAV

lockdiscovery

Supports the "persistent file locking" backend feature. For more information on this property, please refer to the W3C spec.

DAV

resourcetype

The resource’s type. If the resource is a folder, then the value is set to collection, otherwise, no value is returned.

DAV

comments-unread

The number of comments on the item that have yet to be read.

http://owncloud.org/ns

favorite

Indicates whether the file has been favorited or not

http://owncloud.org/ns

fileid

The id of the file

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

share-types

It is an OC-specific property which summarizes what outgoing share types are applied to the current item. The share type values are:

  • 0: user share

  • 1: group share

  • 3: link shares

http://owncloud.org/ns

size

The size of a folder or collection. This property is not returned for files. Refer to the getcontentlength property for folders and collections.

http://owncloud.org/ns

tags

A collection of tags that have been added to the file.

http://owncloud.org/ns

 
<?xml version="1.0" encoding="UTF-8"?>
<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <oc:fileid/>
        <oc:permissions/>
        <oc:size/>
        <oc:owner-id/>
        <oc:owner-display-name/>
        <a:getlastmodified/>
        <a:getetag/>
        <a:getcontenttype/>
    </a:prop>
    <oc:filter-rules>
        <oc:favorite>1</oc:favorite>
    </oc:filter-rules>
</oc:filter-files>
Filtering By Tag

Files can be filtered by those assigned specific tags. If this is required, then the systemtag element needs to be supplied, which contains a space-separated list of tag ids to filter by.

Tag ids can be retrieved by using the Tags API. 
<?xml version="1.0" encoding="UTF-8"?>
<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <oc:fileid/>
        <oc:permissions/>
        <oc:size/>
        <oc:owner-id/>
        <oc:owner-display-name/>
        <a:getlastmodified/>
        <a:getetag/>
        <a:getcontenttype/>
    </a:prop>
    <oc:filter-rules>
        <oc:favorite>1</oc:favorite>
        <oc:systemtag>1</oc:systemtag>
    </oc:filter-rules>
</oc:filter-files>
The example uses xmllint to make the response more readable. Xmllint is available in the libxml2 package.

The Response

Success

Successful requests return two things:

  1. An XML payload.

  2. A status of HTTP/1.1 207 Multi-Status.

You can see an example of the XML payload below. The XML payload contains a response element for each file. And each response element contains three items:

  1. A link to the file (href).

  2. The requested properties, along with their respective values (propstat).

  3. The file’s status (status).

Example of a successful search response
<?xml version="1.0"?>
<d:multistatus 
    xmlns:d="DAV:" 
    xmlns:s="http://sabredav.org/ns" 
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/files/admin/welcome.txt</d:href>
    <d:propstat>
      <d:prop>
        <oc:fileid>28</oc:fileid>
        <oc:permissions>RDNVW</oc:permissions>
        <oc:size>163</oc:size>
        <oc:owner-id>admin</oc:owner-id>
        <oc:owner-display-name>admin</oc:owner-display-name>
        <d:getlastmodified>Mon, 05 Nov 2018 10:52:58 GMT</d:getlastmodified>
        <d:getetag>"91b08390250f5294390c4fc92b6b0138"</d:getetag>
        <d:getcontenttype>text/plain</d:getcontenttype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

Failure

If The Payload File Cannot Be Read Or Is Invalid XML

If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an HTTP/1.1 500 Internal Server Error status code.

<?xml version="1.0" encoding="utf-8"?>
<d:error 
    xmlns:d="DAV:" 
    xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\Xml\ParseException</s:exception>
  <s:message>This should never happen (famous last words)</s:message>
</d:error>
If a Non-Existent Property Is Requested

If a non-existent property is requested, then an additional propstat element is returned, as in the example below, which contains a list of the properties which were not available.

  <d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
  <d:prop>
    <oc:downloadUR/>
  </d:prop>
  <d:status>HTTP/1.1 404 Not Found</d:status>