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}