From c6d67329387f72fac7db35ed49833e01852a73f2 Mon Sep 17 00:00:00 2001
From: sualko <klaus@jsxc.org>
Date: Mon, 27 Dec 2021 15:11:28 +0100
Subject: [PATCH] add description of new OCS endpoint

for recommendations of files and folders

see nextcloud/recommendations#458

Signed-off-by: sualko <klaus@jsxc.org>
---
 developer_manual/client_apis/OCS/index.rst    |  1 +
 .../OCS/ocs-recommendations-api.rst           | 41 +++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 developer_manual/client_apis/OCS/ocs-recommendations-api.rst

diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst
index 1e356151a26..bac1febc253 100644
--- a/developer_manual/client_apis/OCS/index.rst
+++ b/developer_manual/client_apis/OCS/index.rst
@@ -10,3 +10,4 @@ OCS API
    ocs-share-api
    ocs-sharee-api
    ocs-status-api
+   ocs-recommendations-api
diff --git a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst
new file mode 100644
index 00000000000..2b300e49921
--- /dev/null
+++ b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst
@@ -0,0 +1,41 @@
+=======================
+OCS Recommendations API
+=======================
+
+The OCS Recommendations API allows you to get a list of recommended files and folders with recent activity.
+
+.. note:: This API requires the Recommendations app to be enabled.
+
+The base URL for all calls to the share API is: *<nextcloud_base_url>/ocs/v2.php/apps/recommendations/api/v1/*
+
+All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
+
+.. warning:: This API is **experimental** and can change in the future without further notice!
+
+
+Recommendations - Retrieval
+---------------------------
+
+Fetch user-controlled recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Method: ``GET``
+* Endpoint: ``/recommendations``
+* Response:
+    - Status code:
+        + ``200 OK``
+* Result:
+    - `enabled` (boolean) True if recommendations are enabled for user. False otherwise.
+    - `recommendations` (list, optional) List of recommended files and folders, if the user enabled recommendations.
+
+Fetch user setting and recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Method: ``GET``
+* Endpoint: ``/recommendations/always``
+* Response:
+    - Status code:
+        + ``200 OK``
+* Result:
+    - `enabled` (boolean) True if recommendations are enabled for user. False otherwise.
+    - `recommendations` (list) List of recommended files and folders, independent of the users decision.
\ No newline at end of file