Fix API documentation

Signed-off-by: Joas Schilling <coding@schilljs.com>

8 files changed, 106 insertions, 61 deletions

diff --git a/docs/call.md b/docs/call.md
index cd5ce15d9..d61298e54 100644
--- a/docs/call.md
+++ b/docs/call.md
@@ -1,6 +1,8 @@
 # Call API
 
-Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v1 is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
+* Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
 
 ## Get list of connected participants
 
@@ -17,11 +19,14 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
     - Data:
         Array of participants, each participant has at least:
 
-        field | type | Description
-        ------|------|------------
-        `userId` | string | Is empty for guests
-        `lastPing` | int | Timestamp of the last ping of the user (should be used for sorting)
-        `sessionId` | string | 512 character long string
+        field | type | API | Description
+        ------|------|-----|------------
+        `userId` | string | v1 and v2 only | Is empty for guests
+        `actorType` | string | v3 | Actor type of the attendee (see [Constants - Attendee types](constants.md#attendee-types))
+        `actorId` | string | v3 | The user id, guest random id or email address of the attendee
+        `displayName` | string | v3 | The display name of the attendee
+        `lastPing` | int | * | Timestamp of the last ping of the user (should be used for sorting)
+        `sessionId` | string | * | 512 character long string
 
 ## Join a call
 
diff --git a/docs/chat.md b/docs/chat.md
index a2f0c746c..5a7ad2be8 100644
--- a/docs/chat.md
+++ b/docs/chat.md
@@ -133,6 +133,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob
 
 ## Deleting a chat message
 
+* Required capability: `delete-messages`
 * Method: `DELETE`
 * Endpoint: `/chat/{token}/{messageId}`
 
@@ -161,6 +162,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob
 
 ## Mark chat as read
 
+* Required capability: `chat-read-marker`
 * Method: `POST`
 * Endpoint: `/chat/{token}/read`
 * Data:
diff --git a/docs/constants.md b/docs/constants.md
index f8d8e9a6f..383c4c2a8 100644
--- a/docs/constants.md
+++ b/docs/constants.md
@@ -2,22 +2,30 @@
 title: Constants
 ---
 
-## Conversation types
+## Conversation
+
+### Conversation types
 * `1` "one to one"
 * `2` group
 * `3` public
 * `4` changelog
 
-## Read-only states
+### Read-only states
 * `0` read-write
 * `1` read-only
 
-## Listable scope
+### Listable scope
 * `0` participants only
 * `1` regular users only, excluding guest app users
 * `2` everyone
 
-## Participant types
+### Webinary lobby states
+* `0` no lobby
+* `1` lobby for non moderators
+
+## Participants
+
+### Participant types
 * `1` owner
 * `2` moderator
 * `3` user
@@ -25,33 +33,33 @@ title: Constants
 * `5` user following a public link
 * `6` guest with moderator permissions
 
-## Participant in-call flag
+### Participant in-call flag
 * `0` disconnected
 * `1` in-call
 * `2` provides audio
 * `4` provides video
 * `8` uses SIP dial-in
 
-## Participant notification levels
+### Participant notification levels
 * `0` Default (`1` for one-to-one conversations, `2` for other conversations)
 * `1` Always notify
 * `2` Notify on mention
 * `3` Never notify
 
-## Participant read status privacy
+### Participant read status privacy
 * `0` Read status is public
 * `1` Read status is private
 
-## Actor types of chat messages
+### Attendee types
+* `users` - Logged-in users
+* `guests` - Guest without a login
+* `emails` - A guest invited by email address
+
+### Actor types of chat messages
 * `guests` - guest users
 * `users` - logged-in users
 * `bots` - used by commands (actor-id is the used `/command`) and the changelog conversation (actor-id is `changelog`)
 
-## Webinary lobby states
-* `0` no lobby
-* `1` lobby for non moderators
-
-
 ## Signaling modes
 * `internal` No external signaling server is used
 * `external` A single external signaling server is used
diff --git a/docs/conversation.md b/docs/conversation.md
index 446b0a881..45023df01 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -4,24 +4,6 @@
 * Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
 * Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
 
-## Get listed conversations
-
-* Method: `GET`
-* Endpoint: `/listed-room`
-
-* Response:
-    - Status code:
-        + `200 OK`
-        + `401 Unauthorized` when the user is not logged in
-
-    - Header:
-
-        field | type | Description
-        ------|------|------------
-        `searchTerm` | string | search term
-
-    - Data: See array definition in `Get user´s conversations`
-
 ## Get user´s conversations
 
 * Method: `GET`
@@ -65,8 +47,8 @@
         `hasCall` | bool | * | Flag if the conversation has an active call
         `callFlag` | int | v3 | Combined flag of all participants in the current call (see [constants list](constants.md#participant-in-call-flag), only available with `conversation-call-flags` capability)
         `canStartCall` | bool | * | Flag if the user can start a new call in this conversation (joining is always possible) (only available with `start-call-flag` capability)
-        `canDeleteConversation` | bool | 🆕 v2 | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)
-        `canLeaveConversation` | bool | 🆕 v2 | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)
+        `canDeleteConversation` | bool | v2 | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)
+        `canLeaveConversation` | bool | v2 | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)
         `lastActivity` | int | * | Timestamp of the last activity in the conversation, in seconds and UTC time zone
         `isFavorite` | bool | * | Flag if the conversation is favorited by the user
         `notificationLevel` | int | * | The notification level for the user (one of `Participant::NOTIFY_*` (1-3))
@@ -90,7 +72,7 @@
 
     field | type | Description
     ------|------|------------
-    `roomType` | int |
+    `roomType` | int | See [constants list](constants.md#conversation-types)
     `invite` | string | user id (`roomType = 1`), group id (`roomType = 2` - optional), circle id (`roomType = 2`, `source = 'circles'`], only available with `circles-support` capability))
     `source` | string | The source for the invite, only supported on `roomType = 2` for `groups` and `circles` (only available with `circles-support` capability)
     `roomName` | string | conversation name (Not available for `roomType = 1`)
@@ -124,6 +106,25 @@
 
     - Data: See array definition in `Get user´s conversations`
 
+## Get open conversations
+
+* Required capability: `listable-rooms`
+* Method: `GET`
+* Endpoint: `/listed-room`
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `401 Unauthorized` when the user is not logged in
+
+    - Header:
+
+        field | type | Description
+        ------|------|------------
+        `searchTerm` | string | search term
+
+    - Data: See array definition in `Get user´s conversations`
+
 ## Rename a conversation
 
 * Method: `PUT`
@@ -156,8 +157,8 @@
 
 ## Set description for a conversation
 
+* Required capability: `room-description`
 * Method: `PUT`
-* API: v3
 * Endpoint: `/room/{token}/description`
 * Data:
 
@@ -199,6 +200,7 @@
 
 ## Set read-only for a conversation
 
+* Required capability: `read-only-rooms`
 * Method: `PUT`
 * Endpoint: `/room/{token}/read-only`
 * Data:
@@ -283,12 +285,13 @@
 * Response:
     - Status code:
         + `200 OK`
-        + `400 Bad Request` When the the given level is invalid
+        + `400 Bad Request` When the given level is invalid
         + `401 Unauthorized` When the participant is a guest
         + `404 Not Found` When the conversation could not be found for the participant
 
-## Set listable scope for a conversation
+## Open a conversation
 
+* Required capability: `listable-rooms`
 * Method: `PUT`
 * Endpoint: `/room/{token}/listable`
 * Data:
diff --git a/docs/internal-signaling.md b/docs/internal-signaling.md
index 1a4db437a..4fe28f279 100644
--- a/docs/internal-signaling.md
+++ b/docs/internal-signaling.md
@@ -1,6 +1,7 @@
 # Signaling API
 
-Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v1 is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
 
 ## Get signaling settings
 
diff --git a/docs/participant.md b/docs/participant.md
index d1a288942..02afee959 100644
--- a/docs/participant.md
+++ b/docs/participant.md
@@ -26,17 +26,18 @@
 
         field | type | API | Description
         ------|------|-----|------------
-        `userId` | string | v1 + v2| Is empty for guests
+        `userId` | string | v1 + v2 only | Is empty for guests
         `attendeeId` | int | v3 | Unique attendee id
         `actorType` | string | v3 | Currently known `users|guests|emails|groups`
         `actorId` | string | v3 | The unique identifier for the given actor type
-        `displayName` | string | | Can be empty for guests
-        `participantType` | int | | Permissions level of the participant
-        `lastPing` | int | | Timestamp of the last ping of the user (should be used for sorting)
-        `sessionId` | string | | `'0'` if not connected, otherwise a 512 character long string
-        `status` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
-        `statusIcon` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
-        `statusMessage` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
+        `displayName` | string | * | Can be empty for guests
+        `participantType` | int | * | Permissions level of the participant (see [constants list](constants.md#participant-types))
+        `lastPing` | int | * | Timestamp of the last ping of the user (should be used for sorting)
+        `inCall` | int | * | Call flags the user joined with (see [constants list](constants.md#participant-in-call-flag))
+        `sessionId` | string | * | `'0'` if not connected, otherwise a 512 character long string
+        `status` | string | * | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation 
+        `statusIcon` | string | * | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation
+        `statusMessage` | string | * | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation
 
 ## Add a participant to a conversation
 
@@ -87,7 +88,7 @@
 
 ## Delete a participant from a conversation
 
-* API: Only `v1` and `v2`
+* API: Only `v1` and `v2` (Use [Delete an attendee by id from a conversation](#delete-an-attendee-by-id-from-a-conversation) in later version)
 * Method: `DELETE`
 * Endpoint: `/room/{token}/participants`
 * Data:
@@ -119,7 +120,7 @@
 
 ## Remove a guest from a conversation
 
-* API: Only `v1` and `v2`
+* API: Only `v1` and `v2` (Use [Delete an attendee by id from a conversation](#delete-an-attendee-by-id-from-a-conversation) in later versions)
 * Method: `DELETE`
 * Endpoint: `/room/{token}/participants/guests`
 * Data:
@@ -154,11 +155,7 @@
         + `404 Not Found` When the conversation could not be found for the participant
         + `409 Conflict` When the user already has an active session in the conversation. The suggested behaviour is to ask the user whether they want to kill the old session and force join unless the last ping is older than 60 seconds or older than 40 seconds when the conflicting session is not marked as in a call.
 
-    - Data in case of `200 OK`:
-
-        field | type | Description
-        ------|------|------------
-        `sessionId` | string | 512 character long string
+    - Data in case of `200 OK`: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
 
     - Data in case of `409 Conflict`:
 
@@ -170,13 +167,14 @@
 
 ## Resend participant emails
 
+* Required capability: `sip-support`
 * Method: `POST`
 * Endpoint: `/room/{token}/participants/resend-invitations`
 * Data:
 
     field | type | Description
     ------|------|------------
-    `attendeeId` | int or null | v3 | Attendee id can be used for guests and users
+    `attendeeId` | int or null | Attendee id can be used for guests and users
 
 * Response:
     - Status code:
@@ -241,6 +239,7 @@
 Note: This is only allowed with validate SIP bridge requests
 
 * API: Only `v3` or later
+* Required capability: `sip-support`
 * Method: `GET`
 * Endpoint: `/room/{token}/pin/{pin}`
 
@@ -254,6 +253,7 @@ Note: This is only allowed with validate SIP bridge requests
 
 ## Set display name as a guest
 
+* API: Only `v1`
 * Method: `POST`
 * Endpoint: `/guest/{token}/name`
 * Data:
diff --git a/docs/settings.md b/docs/settings.md
index 543190bea..20847e9eb 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -25,3 +25,22 @@ Key | Capability | Default | Valid values
 ----|------------|---------|-------------
 `attachment_folder` | `config => attachments => folder` | `/Talk` | Path owned by the user to store uploads and received shares. It is created if it does not exist.
 `read_status_privacy` | `config => chat => read-privacy` | `0` | One of the read-status constants from the [constants list](constants.md#Participant-read-status-privacy)
+
+## Set SIP settings
+
+* Required capability: `sip-support`
+* Method: `POST`
+* Endpoint: `/settings/sip`
+* Data:
+
+    All values must be sent in the same request
+
+    field | type | Description
+    ------|------|------------
+    `sipGroups` | array | List of group ids that are allow to enable SIP for a conversation
+    `dialInInfo` | string | The dial-in information shown in the sidebar and sent in emails
+    `sharedSecret` | string | The shared secret of the SIP component
+
+* Response:
+    - Status code:
+        + `403 Forbidden` When the user is not an admin
diff --git a/docs/webinar.md b/docs/webinar.md
index ea3f37bf3..3e0d9c119 100644
--- a/docs/webinar.md
+++ b/docs/webinar.md
@@ -6,8 +6,11 @@ Group and public conversations can be used to host webinars. Those online meetin
 * Only moderators can read and write chat messages
 * Normal users can only join the room. They then pull the room endpoint regularly for an update and should start the chat and signaling as well as allowing to join the call, once the lobby got disabled.
 
+## Base endpoint
 
-Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v1 is: `/ocs/v2.php/apps/spreed/api/v1`
+* Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
+* Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
 
 ## Set lobby for a conversation
 
@@ -29,6 +32,8 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
         + `403 Forbidden` When the current user is not a moderator/owner
         + `404 Not Found` When the conversation could not be found for the participant
 
+    - Data: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
+
 ## Enabled or disable SIP dial-in
 
 * Required capability: `sip-support`
@@ -48,3 +53,5 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
         + `403 Forbidden` When the current user is not a moderator/owner
         + `404 Not Found` When the conversation could not be found for the participant
         + `412 Precondition Failed` When SIP is not configured on the server
+
+    - Data: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)