==============
OCS Status API
==============

The OCS Status API allows you to access and modify status API from outside over pre-defined OCS calls.

The base URL for all calls to the share API is: *<nextcloud_base_url>/ocs/v2.php/apps/user_status/api/v1/user_status*

All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.


User Status - Status Manipulation
---------------------------------

Fetch your own status
^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Response:
    - Status code:
        + ``200 OK``
        + ``404 Not Found`` If the user does not have a status set

Set your own status
^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``PUT``
* Endpoint: ``/status``
* Data:

    field | type | Description | Allowed values
    ------|------|-------------|---------------|
    ``statusType`` | string | New status for the authenticated user | ``online``, ``away``, ``dnd``, ``invisible``, ``offline`` | 

* Response:
    - Status code:
        + ``200 OK``
        + ``400 Bad Request`` If the sent status-type is not valid

Set a custom message (predefined)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``PUT``
* Endpoint: ``/message/predefined``
* Data:

    field | type | Description 
    ------|------|------------
    ``messageId`` | string | Message-Id of the predefined message
    ``clearAt``   | int    | Unix Timestamp representing the time to clear the status

* Response:
    - Status code:
        + ``200 OK``
        + ``400 Bad Request`` If the sent messageId does not exist
        + ``400 Bad Request`` If the Unix timestamp is in the past

Set a custom message (user-defined)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``, ``supports_emoji`` for ``statusIcon`` support
* Method: ``PUT``
* Endpoint: ``/message/custom``
* Data:

    field | type | Description 
    ------|------|------------
    ``statusIcon`` | string/null | The icon picked by the user (must be an emoji, at most one)
    ``message``    | string      | The custom message picked by the user
    ``clearAt``    | int         | Unix Timestamp representing the time to clear the status

* Response:
    - Status code:
        + ``200 OK``
        + ``400 Bad Request`` If the `statusIcon` is not a an emoji or more than one emoji
        + ``400 Bad Request`` If the `message` is too long
        + ``400 Bad Request`` If the Unix timestamp is in the past

Clear message
^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``DELETE``
* Endpoint: ``/message``
* Response:
    - Status code:
        + ``200 OK``

User Status - Predefined statuses
---------------------------------

Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/predefined_statuses``

Fetch the list of predefined statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Response:
    - Status code:
        + ``200 OK``

User Status - Retrieve statuses
-------------------------------

Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/statuses``

Fetch a list of all set user-statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Data:

    field | type | Description 
    ------|------|------------
    ``limit``  | int | Limit for pagination
    ``offset`` | int | Offset for pagination

* Response:
    - Status code:
        + ``200 OK``

Fetch a specific user's status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/{userId}``
* Response:
    - Status code:
        + ``200 OK``
        + ``404 Not Found`` If the user does not have a status set

Files Sharing 
^^^^^^^^^^^^^

The user-status is also exposed via the following Files Sharing APIs:
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees``
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees_recommended``
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares``
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/inherited``
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/pending``
 * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``
 * ``POST /ocs/v2.php/apps/files_sharing//api/v1/shares``
 * ``PUT /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``
