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 Status 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

Fetch a user's backup status

In some scenarios the user's status can be overwritten automatically, e.g. by joining a call in Nextcloud Talk, or when the availability automation is enabled. In this case the userId can be prefixed with an _ underscore, to get the original user status. When a user status is returned and the user_status > restore capability is available, the backup status should be added as an item in the predefined status list. Clicking that should then do an API call to User status - Restore backup should be done.

  • Required capability: user_status

  • Method: GET

  • Endpoint: /_{userId}

  • Response:
    • Status code:

      • 200 OK

      • 404 Not Found If the user does not have a backup 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}

User status - Restore backup