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}