OCS APIs overview¶
This document provides a quick overview of the OCS API endpoints supported in Nextcloud.
All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies, if not stated otherwise.
Testing requests with curl¶
All OCS requests can be easily tested out using
curl by specifying the request method (
PUT, etc) and setting a request body where needed.
For example: you can perform a
GET request to get information about a user:
curl -u username:password -X GET 'https://cloud.example.com/ocs/v1.php/...' -H "OCS-APIRequest: true"
Since: 11.0.2, 12.0.0
This request returns the available metadata of a user. Admin users can see the information of all users, while a default user only can access it’s own metadata.
<?xml version="1.0"?> <ocs> <meta> <status>ok</status> <statuscode>100</statuscode> <message>OK</message> <totalitems></totalitems> <itemsperpage></itemsperpage> </meta> <data> <enabled>true</enabled> <quota> <free>338696790016</free> <used>7438874</used> <total>338704228890</total> <relative>0</relative> <quota>-3</quota> </quota> <email>email@example.com</email> <displayname>admin</displayname> <phone></phone> <address></address> <webpage></webpage> <twitter>schiessle</twitter> </data> </ocs>
Clients can obtain capabilities provided by the Nextcloud server and its apps via the capabilities OCS API.
<?xml version="1.0"?> <ocs> <meta> <status>ok</status> <statuscode>100</statuscode> <message>OK</message> <totalitems></totalitems> <itemsperpage></itemsperpage> </meta> <data> <version> <major>12</major> <minor>0</minor> <micro>0</micro> <string>12.0 beta 4</string> <edition></edition> </version> <capabilities> <core> <pollinterval>60</pollinterval> <webdav-root>remote.php/webdav</webdav-root> </core> </capabilities> </data> </ocs>
Values of the theming app are exposed though the capabilities API, allowing client developers to adjust the look of clients to the theming of different Nextcloud instances.
<theming> <name>Nextcloud</name> <url>https://nextcloud.com</url> <slogan>A safe home for all your data</slogan> <color>#0082c9</color> <logo>http://cloud.example.com/index.php/apps/theming/logo?v=1</logo> <background>http://cloud.example.com/index.php/apps/theming/logo?v=1</background> </theming>
The background value can either be an URL to the background image or a hex color value.
It might be required to give a 3rd party access to a file however you do not want to hand over credentials to the 3rd party. An example of this is playing files in an external media player on mobile devices.
To solve this issue there is a way to request a unique public link to a single. This link will be valid for 24 hours after wards it will be removed.
To obtain a direct link:
fileId in the body (so
fileId=42 for example).
This will then return you the link to use to obtain the file.
Auto-complete and user search¶
It is possible to search for users using the auto-complete API, used to auto-complete usernames in comments, chat or to find guest accounts. The code can be found here
An example curl command would be:
curl -i -u master -X GET -H "OCS-APIRequest: true" 'https://my.nextcloud/ocs/v2.php/core/autocomplete/get?search=JOANNE%40EMAIL.ISP&itemType=%20&itemId=%20&shareTypes=8&limit=2'
That would look for JOANNE@EMAIL.ISP as guest user. Maximum 2 results to be returned for a regular user, the shareTypes array would carry only “0”.
itemId are left (set to a white space), essentially they are to give context about the use case, so sorters can do their work (like who
commented last). It can be an option for filtering on a later stage but you can also leave them out as per the below example.
curl -i -u master -X GET -H "OCS-APIRequest: true" 'https://my.nextcloud/ocs/v2.php/core/autocomplete/get?search=JOANNE%40EMAIL.ISP&shareTypes=8&limit=2'
The shareType would default to regular users if you left it out), the limit defaults to 10.