Search API

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; these are:

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.

Filtering By Filename Pattern

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>
Limiting The Number Of Results Returned

To limit the number of results returned, use the limit element of the search element, as in the following example. It will limit the maximum number of results returned to five.

<?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:limit>5</oc:limit>
    </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

id

The id of the file

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

size

The file’s size

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

getlastmodified

The last modified date of the file

DAV

getetag

The file’s ETag

DAV

getcontenttype

The file’s content type.

DAV

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <oc:id/>
        <oc:downloadURL/>
        <oc:fileid/>
        <oc:permissions/>
        <oc:size/>
        <oc:owner-id/>
        <oc:owner-display-name/>
        <a:getlastmodified/>
        <a:getetag/>
        <a:getcontenttype/>
    </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.

<?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/Website%20Plan.md</d:href>
    <d:propstat>
      <d:prop>
        <oc:id>00000065oc21s4c9iej2</oc:id>
        <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:propstat>
      <d:prop>
        <oc:downloadUR/>
      </d:prop>
      <d:status>HTTP/1.1 404 Not Found</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

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

id

The id of the file

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

size

The file’s size

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

getlastmodified

The last modified date of the file

DAV

getetag

The file’s ETag

DAV

getcontenttype

The file’s content type.

DAV

<?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.

<?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/Website%20Plan.md</d:href>
    <d:propstat>
      <d:prop>
        <oc:id>00000065oc21s4c9iej2</oc:id>
        <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:propstat>
      <d:prop>
        <oc:downloadUR/>
      </d:prop>
      <d:status>HTTP/1.1 404 Not Found</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>