Allow users to set a status

This can be done trough the API for the current user, or on the
profile page.

1 files changed, 63 insertions, 0 deletions

diff --git a/doc/api/users.md b/doc/api/users.md
index 07f9baf06d2..481219de0f1 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -440,6 +440,67 @@ GET /user
 }
 ```
 
+## User status
+
+Get the status of the currently signed in user.
+
+```
+GET /user/status
+```
+
+```json
+{
+  "emoji":"coffee",
+  "message":"I crave coffee"
+}
+```
+
+## Get the status of a user
+
+Get the status of a user.
+
+```
+GET /users/:id_or_username/status
+```
+
+```json
+{
+  "emoji":"coffee",
+  "message":"I crave coffee"
+}
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id_or_username` | string | yes    | The id or username of the user to get a status of |
+
+
+## Set user status
+
+Set the status of the current user.
+
+```
+PUT /user/status
+```
+
+```json
+{
+  "emoji":"coffee",
+  "message":"I crave coffee"
+}
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `emoji`   | string | no     | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. |
+| `message` | string | no | The message to set as a status |
+
+When both parameters are empty, the status will be cleared.
+
 ## List user projects
 
 Please refer to the [List of user projects ](projects.md#list-user-projects).
@@ -1167,3 +1228,5 @@ Example response:
 ```
 
 Please note that `last_activity_at` is deprecated, please use `last_activity_on`.
+
+[gemojione-index]: https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json