openapi: 3.0.0 info: version: 1.0.0 title: Rooms # description: |- # Conversations take place in rooms. This section includes the following: # * **Groups**: Organize discussions with groups or channels. # * **Channels**: Create and manage dedicated [channels](https://docs.rocket.chat/use-rocket.chat/user-guides/rooms/channels) for various topics. # * **Rooms**: Manage rooms and modify room settings. # * **Teams**: Create and manage [teams](https://docs.rocket.chat/use-rocket.chat/user-guides/rooms/teams) and team members. # * **Directory**: Search workspace users, teams, and channels. servers: - url: https://apiexplorer.support.rocket.chat paths: /api/v1/channels.create: post: tags: - Channels summary: Create Channel description: |- Create a public channel. Optionally, include specified users. The channel creator is included as a member by default. Permission required: `create-c`. Channel naming has restraints following the regex filter `[0-9a-zA-Z-_.]+` by default. See UTF8 Settings to modify regex filter for channel names. Channel names must not allow for any whitespaces. ### Changelog | Version | Description | | ------- | ------------------------- | | 6.4.1 | Added `excludeSelf` param | | 0.13.0 | Added | operationId: post-api-v1-channels.create parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the channel. members: type: array description: An array of the users to be added to the channel when it is created. items: type: string readOnly: type: boolean description: Set if the channel is read only or not. It is `false` by default. excludeSelf: type: boolean description: 'If set to true, the user calling the endpoint is not automatically added as a member of the channel. The default `value` is false.' customFields: type: object description: |- If you have defined custom fields for your workspace, you can provide them in this object parameter. For details, see the Custom Fields document. extraData: type: object description: |- Additional channel settings applied at creation. For more information, see Channels. additionalProperties: false properties: broadcast: type: boolean description: Whether the channel should be a broadcast room. encrypted: type: boolean description: Whether the channel should be encrypted. teamId: type: string description: An existing team ID to associate with this channel. Requires the `create-team-channel` permission. topic: type: string description: The topic of the channel. federated: type: boolean description: Whether the channel should be federated (Matrix federation). required: - name examples: Example: value: name: channelname members: - rocket.cat readOnly: true excludeSelf: true customFields: type: default extraData: broadcast: true encrypted: false teamId: 658441562dd9f928ad9951aa responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string _updatedAt: type: string customFields: type: object name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string name: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean success: type: boolean examples: Example: value: channel: _id: ByehQjC44FwMeiLbX name: channelname t: c usernames: - example msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: example ts: '2016-05-30T13:42:25.304Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.addAll: post: tags: - Channels summary: Add all Users to a Channel description: |- Adds all users in the workspace to a public room. Permission required: `add-all-to-room`. The maximum number of users you can add at once depends on your workspace's REST API settings. To access this setting, go to **Manage** > **Workspace** > **Settings** > **General** > **REST API** > **User Limit for Adding All Users to Channel**. ### Changelog | Version | Description | | ------- | ------------------------- | |0.55.0 | Added `activeUsersOnly` param | |0.48.0 | Renamed to `channels.addAll` from `channel.addAll`| operationId: post-api-v1-channels.addAll parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. activeUsersOnly: type: boolean description: Add only active users. It is `false` by default. required: - roomId examples: Example: value: roomId: WDuJLFkjwk6L7LdFC activeUsersOnly: true responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string success: type: boolean examples: Success: value: channel: _id: ByehQjC44FwMeiLbX name: channelname t: c usernames: - example - rocket.cat msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: example ts: '2016-05-30T13:42:25.304Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.addLeader: post: tags: - Channels summary: Add Channel Leader description: |- Assign the role of `leader` to a channel member. See Room Roles for details about the roles. Permission required: `set-leader` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.75.0 | Added | operationId: post-api-v1-channels.addLeader parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. userId: type: string description: The ID of the user to be made leader. required: - roomId - userId examples: Example: value: roomId: WDuJLFkjwk6L7LdFC userId: b66oZ8i9pkeSko33v responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User is a leader: value: success: false error: 'User is already a leader [error-user-already-leader]' errorType: error-user-already-leader '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.addModerator: post: tags: - Channels summary: Add Channel Moderator description: |- Assign the `moderator` role to a channel member. See Room Roles for details about the roles. Permission required: `set-moderator` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.49.4 | Added | operationId: post-api-v1-channels.addModerator parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. userId: type: string description: The user ID that you want to set as the moderator. required: - roomId - userId examples: Example: value: roomId: WDuJLFkjwk6L7LdFC userId: b66oZ8i9pkeSko33v responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User is already a moderator: value: success: false error: 'User is already a moderator [error-user-already-moderator]' errorType: error-user-already-moderator '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.addOwner: post: tags: - Channels summary: Add Channel Owner description: |- Assign the `owner` role to a channel member. See Room Roles for details about the roles. Permission required: `set-owner` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.49.4 | Added | operationId: post-api-v1-channels.addOwner parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. userId: type: string description: The user ID that you want to set as the channel owner. required: - roomId - userId examples: Example: value: roomId: WDuJLFkjwk6L7LdFC userId: b66oZ8i9pkeSko33v responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: User is alrready an owner: value: success: false error: 'User is already an owner [error-user-already-owner]' errorType: error-user-already-owner details: method: addRoomOwner '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.anonymousread: get: tags: - Channels summary: Read Channel Messages Anonymously description: |- Fetch the messages in a public channel to an anonymous user. You must enable `Accounts_AllowAnonymousRead` setting in the workspace. ### Changelog | Version | Description | | ------- | ------------------------- | | 1.2.0 | Added | operationId: get-api-v1-channels.anonymousread parameters: - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' responses: '200': description: OK content: application/json: schema: type: object properties: messages: type: array items: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string attachments: type: array items: $ref: '#/components/schemas/Attachment' count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: messages: - _id: xadufzmxzYQp4H9py alias: test msg: Example message attachments: [ ] parseUrls: true bot: i: MnQyfhWt5LqZotyfc groupable: false ts: '2018-10-05T01:10:47.524Z' u: _id: rocket.cat username: rocket.cat name: Rocket.Cat rid: GENERAL _updatedAt: '2018-10-05T13:42:51.163Z' reactions: ':grin:': usernames: - marco.zoo mentions: [ ] channels: [ ] starred: _id: KPkEYwKKBKZnEEPpt - _id: id-1538701845987 rid: GENERAL msg: This message was edited via API alias: Gruggy emoji: ':smirk:' avatar: 'http://res.guggy.com/logo_128.png' attachments: - collapsed: false color: '#ff0000' text: Yay for gruggy! ts: '2016-12-09T16:53:06.761Z' message_link: 'https://google.com' thumb_url: 'http://res.guggy.com/logo_128.png' author_name: Bradley Hilton author_link: 'https://rocket.chat/' author_icon: 'https://avatars.githubusercontent.com/u/850391?v=3' title: Attachment Example title_link: 'https://youtube.com' title_link_download: true image_url: 'http://res.guggy.com/logo_128.png' audio_url: 'http://www.w3schools.com/tags/horse.mp3' video_url: 'http://www.w3schools.com/tags/movie.mp4' fields: - short: true title: Test value: Testing out something or other - short: true title: Another Test value: 'Link something and this and that.' ts: '2018-10-05T01:10:45.994Z' u: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test name: RocketChat Internal Admin Test _updatedAt: '2018-10-05T01:10:47.064Z' editedBy: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test editedAt: '2018-10-05T01:10:46.384Z' reactions: ':smile:': usernames: - rocketchat.internal.admin.test ':squid:': usernames: - rocketchat.internal.admin.test ':bee:': usernames: - rocketchat.internal.admin.test ':ant:': usernames: - rocketchat.internal.admin.test mentions: [ ] channels: [ ] urls: [ ] count: 2 offset: 0 total: 2 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any channel [error-room-not-found]' errorType: error-room-not-found /api/v1/channels.archive: post: tags: - Channels summary: Archive Channel description: |- Archive a channel. Permission required: `archive-room` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: post-api-v1-channels.archive parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID that you want to archive. required: - roomId examples: Example: value: roomId: ByehQjC44FwMeiLbX responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Channel is already archived: value: success: false error: 'The channel, add-room-websocket, is archived [error-room-archived]' errorType: error-room-archived '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.close: post: tags: - Channels summary: Close Channel description: |- Remove a channel from the user's list of channels in the workspace sidebar. You can access it again from the **Directory**. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: post-api-v1-channels.close parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID that you want to close from your list. required: - roomId examples: Example: value: roomId: ByehQjC44FwMeiLbX responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Channel is already closed: value: success: false error: 'The channel, dlp, is already closed to the sender' '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.counters: get: tags: - Channels summary: Get Channel Counters description: |- Gets channel counter for the authenticated user. Permission required: `view-room-administration` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.65.0 | Added | operationId: get-api-v1-channels.counters parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - name: userId in: query description: The user ID. schema: type: string example: RtycPC29hqLJfT9xj responses: '200': description: |- OK **Note** - `joined` boolean flag whether the user has joined the room or not. - `members` is the count of current room members. - `unreads` is the count of unread messages for the specified user (for the calling user or the provided user ID). - `unreadsFrom` is the start date-time of unread interval for the specified user. - `msgs` is the count of messages in the room. - `latest` is the end date-time of unread interval for the specified user (or date-time of last posted message). - `userMentions` is the count of user mentions in messages. content: application/json: schema: type: object properties: joined: type: boolean members: type: integer unreads: type: integer unreadsFrom: type: string msgs: type: integer latest: type: string userMentions: type: integer success: type: boolean examples: Example: value: joined: true members: 23 unreads: 2 unreadsFrom: '2023-09-12T16:33:11.644Z' msgs: 7345 latest: '2023-09-25T22:50:07.979Z' userMentions: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.delete: post: tags: - Channels summary: Delete Channel description: |- Delete a channel. Any of the permssions are required: * `delete-c`: Delete a public channel. * `delete-team-channel`: Delete a channel part of a team. You also need the `delete-c` permission. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.71.0 | Removed `channel` property| | 0.49.0 | Added | operationId: post-api-v1-channels.delete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: Enter the room ID. This parameter is required if no `roomName` is provided. roomName: type: string example: general description: Enter the room name. This parameter is required if no `roomId` is provided. responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.files: get: tags: - Channels summary: Get Channel Files description: |- Retrieves all the media files from a channel. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.64.0 | Change userId to user object in response | | 0.59.0 | Added | operationId: get-api-v1-channels.files parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/filterTypeGroup' - $ref: '#/components/parameters/filterName' responses: '200': description: OK content: application/json: schema: type: object properties: files: type: array items: type: object properties: _id: type: string name: type: string size: type: integer type: type: string rid: type: string userId: type: string store: type: string _updatedAt: type: string identify: type: object properties: format: type: string size: type: object properties: width: type: integer height: type: integer complete: type: boolean etag: type: string path: type: string progress: type: integer token: type: string uploadedAt: type: string uploading: type: boolean url: type: string typeGroup: type: string user: type: object properties: _id: type: string username: type: string name: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Example: value: files: - _id: 651227bea2f73c7460e18c63 name: Screenshot (317).png size: 288727 type: image/png rid: siyr2oWQJBjQjhLwr userId: rbAXPnMktTFbNpwtJ store: 'GridFS:Uploads' _updatedAt: '2023-09-26T00:37:19.598Z' identify: format: png size: width: 1920 height: 1080 complete: true etag: 2Q2D8hSxCdhQLzcpx path: '/ufs/GridFS:Uploads/651227bea2f73c7460e18c63/Screenshot%20(317).png' progress: 1 token: da2aCAf88a uploadedAt: '2023-09-26T00:37:18.168Z' uploading: false url: 'http://localhost:3000/ufs/GridFS:Uploads/651227bea2f73c7460e18c63/Screenshot%20(317).png' typeGroup: image user: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test - _id: 64b589e6aa5ad4273bfc4db6 name: eicar.zip size: 266 type: application/x-zip-compressed rid: siyr2oWQJBjQjhLwr userId: rbAXPnMktTFbNpwtJ store: 'GridFS:Uploads' _updatedAt: '2023-07-17T18:35:18.242Z' complete: true etag: JYaAzzFQSnxYQ7rWW path: '/ufs/GridFS:Uploads/64b589e6aa5ad4273bfc4db6/eicar.zip' progress: 1 token: 7a1A38Cb5a uploadedAt: '2023-07-17T18:35:18.216Z' uploading: false url: 'http://localhost:3000/ufs/GridFS:Uploads/64b589e6aa5ad4273bfc4db6/eicar.zip' typeGroup: application user: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test count: 2 offset: 0 total: 2 success: true /api/v1/channels.history: get: tags: - Channels summary: Get Channel History description: |- Retrieves the history of a channel. You must be a member of the channel or have the `preview-c-room` permission. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.75.0 | Added offset property | | 0.47.0 | Added | operationId: get-api-v1-channels.history parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - name: latest in: query description: The end of time range of messages to retrieve. The default value is the current date and time. schema: type: string example: '2016-09-30T13:42:25.304Z' - name: oldest in: query description: The start of the time range of messages to retrieve schema: type: string example: '2016-05-30T13:42:25.304Z' - name: inclusive in: query description: Whether messages which land on the latest and oldest dates should be included. The default value is false. schema: type: boolean example: true - name: showThreadMessages in: query description: 'Whether thread messages should be included in the response' schema: type: boolean example: true - name: unreads in: query description: Whether the number of unread messages should be included. The default value is false. schema: type: boolean example: false responses: '200': description: OK content: application/json: schema: type: object properties: files: type: array items: type: object properties: _id: type: string name: type: string size: type: integer type: type: string rid: type: string userId: type: string store: type: string _updatedAt: type: string identify: type: object properties: format: type: string size: type: object properties: width: type: integer height: type: integer complete: type: boolean etag: type: string path: type: string progress: type: integer token: type: string uploadedAt: type: string uploading: type: boolean url: type: string typeGroup: type: string user: type: object properties: _id: type: string username: type: string name: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Example: value: messages: - _id: AkzpHAvZpdnuchw2a rid: ByehQjC44FwMeiLbX msg: hi ts: '2016-12-09T12:50:51.555Z' u: _id: y65tAmHs93aDChMWu username: testing _updatedAt: '2016-12-09T12:50:51.562Z' - _id: vkLMxcctR4MuTxreF t: uj rid: ByehQjC44FwMeiLbX ts: '2016-12-08T15:41:37.730Z' msg: testing2 u: _id: bRtgdhzM6PD9F8pSx username: testing2 groupable: false _updatedAt: '2016-12-08T16:03:25.235Z' - _id: bfRW658nEyEBg75rc t: uj rid: ByehQjC44FwMeiLbX ts: '2016-12-07T15:47:49.099Z' msg: testing u: _id: nSYqWzZ4GsKTX4dyK username: testing1 groupable: false _updatedAt: '2016-12-07T15:47:49.099Z' - _id: pbuFiGadhRZTKouhB t: uj rid: ByehQjC44FwMeiLbX ts: '2016-12-06T17:57:38.635Z' msg: testing u: _id: y65tAmHs93aDChMWu username: testing groupable: false _updatedAt: '2016-12-06T17:57:38.635Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.info: get: tags: - Channels summary: Get Channel Information description: |- Retrieves the information about the channel. This does not include archived channels. You must be a member of the channel. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: get-api-v1-channels.info parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string success: type: boolean examples: Example: value: channel: _id: ByehQjC44FwMeiLbX name: testing fname: testing t: c msgs: 0 usersCount: 2 u: _id: HKKPmF8rZh45GMHWH username: marcos.defendi customFields: { } broadcast: false encrypted: false ts: '2020-05-21T13:14:07.070Z' ro: false default: false sysMes: true _updatedAt: '2020-05-21T13:14:07.096Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.invite: post: tags: - Channels summary: Add Users to Channel description: |- Add a user or bulk users to a channel. For a user to invite other users, they must match at least one of the following premises: - The user is part of a room of any type and has the `add-user-to-joined-room` permission. - The user is part of a public room `(t: 'c')` and has the `add-user-to-any-c-room` permission. - The user is part of a private room `(t: 'p')` and has the `add-user-to-any-p-room` permission. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: post-api-v1-channels.invite parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object oneOf: - type: object properties: roomId: type: string description: The channel's ID. example: nSYqWzZ4GsKTX4dyK userId: type: string description: The user id to be invited. example: ByehQjC44FwMeiLbX required: - roomId - userId - type: object properties: roomId: type: string description: The channel's id example: nSYqWzZ4GsKTX4dyK userIds: type: array description: An array of the userId of users to be invited items: type: object properties: type: type: string value: type: string required: - roomId - userIds responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object success: type: boolean examples: Add bulk users: value: channel: _id: ByehQjC44FwMeiLbX ts: '2016-11-30T21:23:04.737Z' t: c name: testing usernames: - testing - testing1 msgs: 1 _updatedAt: '2016-12-09T12:50:51.575Z' lm: '2016-12-09T12:50:51.555Z' success: true Add a user: value: channel: _id: ByehQjC44FwMeiLbX ts: '2016-11-30T21:23:04.737Z' t: c name: testing usernames: testing msgs: 1 _updatedAt: '2016-12-09T12:50:51.575Z' lm: '2016-12-09T12:50:51.555Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.join: post: tags: - Channels summary: Join a Channel description: |- Join a public channel. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.49.0 | Added | operationId: post-api-v1-channels.join parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. joinCode: type: string description: |- The join code of the room. Channels can be password-protected. In that case, users must enter the password for access. See Channel information for details. The join code isn't needed if the user has the `join-without-join-code` permission. required: - roomId examples: Example: value: roomId: ByehQjC44FwMeiLbX joinCode: '1234' responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string success: type: boolean examples: Example: value: channel: _id: nxXKHF2o2nzKYtFMM name: test fname: test t: c msgs: 8 usersCount: 2 u: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test customFields: { } broadcast: false encrypted: false ts: '2019-01-16T12:00:04.783Z' ro: false sysMes: true default: false _updatedAt: '2019-01-16T12:06:30.426Z' joinCodeRequired: true success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.kick: post: tags: - Channels summary: Remove User from Channel description: |- Remove a user from the channel. Permissions required: * `remove-user`: To remove a user from any room. * `kick-user-from-any-c-room`: To remove a user from a public channel. You also need the `remove-user` permission. ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: post-api-v1-channels.kick requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id userId: type: string description: The id of the user to be removed. required: - roomId - userId examples: Example: value: roomId: WDuJLFkjwk6L7LdFC userId: rYhzFRd2QZjNwAAXX responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string success: type: boolean examples: Example: value: channel: _id: ByehQjC44FwMeiLbX name: invite-me t: c usernames: - testing1 msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.leave: post: tags: - Channels summary: Leave Channel description: |- Leave a public channel. Permission required: `leave-c` ### Changelog | Version | Description | | ------- | ------------------------- | | 0.48.0 | Added | operationId: post-api-v1-channels.leave parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The channel ID that you want to leave. responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Example: value: channel: _id: ByehQjC44FwMeiLbX name: invite-me t: c usernames: - testing2 msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.list.joined: get: tags: - Channels summary: Get List of Joined Channels description: |- Lists all the channels the authenticated user has joined. ### Changelog | Version | Description | | ------- | -------------------------------------------- | | 0.62.0 | Add `query` parameter support. | | 0.49.0 | Count and offset query parameters supported. | | 0.48.0 | Added | operationId: get-api-v1-channels.list.joined parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' responses: '200': description: OK content: application/json: schema: type: object properties: channels: type: array items: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string topic: type: string muted: type: array items: type: object unmuted: type: array items: type: string offset: type: integer count: type: integer total: type: integer success: type: boolean examples: Example: value: channels: - _id: ByehQjC44FwMeiLbX name: invite-me t: c usernames: - testing1 msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.list: get: tags: - Channels summary: Get Channel List description: |- Lists all the channels in the workspace. Any of the following permissions are required: * `view-c-room` * `view-joined-room` ### Changelog | Version | Description | | ------- | -------------------------------------------- | | 0.49.0 | Count and offset query parameters supported. | | 0.48.0 | Added | operationId: get-api-v1-channels.list parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' - schema: type: string in: query name: sort description: |- Sort the channels in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON object. The options are as follows: * `name`: Sort by the channel name. For example, `sort={"name":1}` (this is the default sorting mechanism). * `ts`: Sort by channel creation timestamp. For example, `sort={"ts":-1}` * `usersCount`: Sort by the number of users in the channel. For example, `sort={"usersCount":1}` responses: '200': description: OK content: application/json: schema: type: object properties: channels: type: array items: type: object properties: _id: type: string fname: type: string customFields: type: object topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string text: type: object properties: type: type: string text: type: string blockId: type: string appId: type: string elements: type: array items: type: object properties: type: type: string text: type: string emoji: type: boolean editedAt: type: string editedBy: type: object properties: _id: type: string username: type: string lm: type: string description: type: string federated: type: boolean count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: channels: - _id: GENERAL ts: '2024-02-14T14:34:49.365Z' t: c name: general usernames: [ ] msgs: 6 usersCount: 6 _updatedAt: '2024-03-26T17:40:18.321Z' u: _id: rocket.cat username: rocket.cat name: Rocket.Cat default: true - _id: 65fd8a6bf581e473b56471ba fname: test-channel _updatedAt: '2024-03-22T13:40:59.620Z' customFields: { } topic: '' broadcast: false encrypted: false name: test-channel t: c msgs: 0 usersCount: 1 u: _id: GdEsNbLxzoBgG8XoQ username: apiadmin name: apiadmin ts: '2024-03-22T13:40:59.577Z' ro: false default: false sysMes: true count: 2 offset: 0 total: 3 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.members: get: tags: - Channels summary: Get Members of a Channel description: |- Lists all channel users. The list of elements a user can use to sort the list is limited. The current sortable element is: `username`. If the channel is a broadcast channel, you need the `view-broadcast-member-list` permission. ### Changelog | Version | Description | | ------- | -------------------------------------------- | | 0.59.0 | Added | operationId: get-api-v1-channels.members parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - name: status in: query description: The user's status (search filter). schema: type: array items: type: string example: '[''online'', ''away'']' - name: filter in: query description: Extra search filters to be applied to the fields defined in the `Accounts_SearchFields`setting. schema: type: string example: my-nickname - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' responses: '200': description: OK content: application/json: schema: type: object properties: members: type: array items: type: object properties: _id: type: string username: type: string status: type: string _updatedAt: type: string name: type: string nickname: type: string avatarETag: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: members: - _id: rbAXPnMktTFbNpwtJ username: roxie status: offline _updatedAt: '2023-09-24T22:27:33.610Z' name: test test nickname: baby girl - _id: 5fRTXMt7DMJbpPJfh username: test.test status: offline _updatedAt: '2023-09-16T08:33:38.123Z' name: Testtest avatarETag: GFoEi6wv3uAxnzDcD nickname: test.test count: 2 offset: 0 total: 2 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.messages: get: tags: - Channels summary: Get Channel Messages description: |- Lists all the channel's messages. Permissions required: `view-c-room`, `view-joined-room` ### Changelog | Version | Description | | ------- | -------------------------------------------- | | 7.0.0 | Added `mentionIds`, `starredIds`, `pinned` query parameters.| | 0.59.0 | Added | operationId: get-api-v1-channels.messages parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/RoomId' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/offset' - name: mentionIds in: query description: Filter the messages where a user has been mentioned by the userId. For a set of userIds, use an array (`["838ndhd79w", "dud0wu900"]`). schema: type: string example: '838ndhd79w' - name: starredIds in: query description: Filter the messages a user have starred by userId. For a set of userIds, use an array (`["838ndhd79w", "dud0wu900"]`). schema: type: string example: 'dud0wu900' - name: pinned in: query description: Filter pinned messages. schema: type: string example: 'true' responses: '200': description: OK content: application/json: schema: type: object properties: messages: type: array items: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string replies: type: array items: type: string tcount: type: integer tlm: type: string attachments: type: array items: $ref: '#/components/schemas/Attachment' editedAt: type: string editedBy: type: object properties: _id: type: string username: type: string reactions: type: object t: type: string _hidden: type: boolean parent: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: messages: - _id: uASTuwBEu7SBDAxxh rid: 6513afeda2f73c7460e18c86 msg: threaads produced links ts: '2023-09-27T04:36:47.522Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-27T04:36:47.698Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: threaads produced links - _id: B7Yms4bCvgJsitrBq rid: 6513afeda2f73c7460e18c86 msg: always do ts: '2023-09-27T04:34:38.818Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-27T04:34:38.900Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: always do - _id: 3rfQYmS8MzCKnQbcu rid: 6513afeda2f73c7460e18c86 msg: '' ts: '2023-09-27T04:34:34.259Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-27T04:36:38.258Z' urls: [ ] mentions: [ ] channels: [ ] replies: - rbAXPnMktTFbNpwtJ tcount: 0 tlm: '2023-09-27T04:34:50.746Z' attachments: [ ] editedAt: '2023-09-27T04:36:19.494Z' editedBy: _id: rbAXPnMktTFbNpwtJ username: roxie reactions: { } t: rm - _id: 6513b143a2f73c7460e18c88 rid: 6513afeda2f73c7460e18c86 msg: test messages ts: '2023-09-27T04:34:34.259Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-27T04:36:19.486Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: test messages replies: - rbAXPnMktTFbNpwtJ tcount: 1 tlm: '2023-09-27T04:34:50.746Z' _hidden: true parent: 3rfQYmS8MzCKnQbcu editedAt: '2023-09-27T04:36:19.485Z' editedBy: _id: rbAXPnMktTFbNpwtJ username: roxie count: 4 offset: 0 total: 4 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.moderators: get: tags: - Channels summary: Get Channel Moderators description: |- List all the moderators in a channel. ### Changelog | Version | Description | | ------- | ----------- | | 0.70.0 | Added | operationId: get-api-v1-channels.moderators parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' responses: '200': description: OK content: application/json: schema: type: object properties: moderators: type: array items: type: object properties: _id: type: string username: type: string name: type: string success: type: boolean examples: Success: value: moderators: - _id: rocket.cat username: rocket.cat name: Rocket.Cat success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.online: get: tags: - Channels summary: List Online Users in a Channel description: |- List all online users in a particular channel. ### Changelog | Version | Description | | ------- | ----------- | |0.52.0 | Added | |7.0.0 | Replaced `query` parameter with `_id` parameter | operationId: get-api-v1-channels.online parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: _id in: query description: The channel's id. required: true schema: type: string example: "5HmCfpoB7jp2uibTC" responses: '200': description: OK content: application/json: schema: type: object properties: online: type: array items: type: object properties: _id: type: string username: type: string success: type: boolean examples: Example: value: online: - _id: 47cRd58HnWwpqxhaZ username: test - _id: BsxzC22xQ43taWdff username: uniqueusername success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.open: post: tags: - Channels summary: Add Channel to User List description: |- Add a channel back to the user's list of channels in the workspace's sidebar. ### Changelog | Version | Description | | ------- | ----------- | |0.48.0 | Added | operationId: post-api-v1-channels.open parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. required: - roomId examples: Example: value: roomId: ByehQjC44FwMeiLbX responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.removeLeader: post: tags: - Channels summary: Remove Channel Leader description: | Remove the `leader` role from a user in a channel. Permission required: `set-leader` . ### Changelog | Version | Description | | ------- | ----------- | |0.75.0 | Added | operationId: post-api-v1-channels.removeLeader parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id userId: type: string description: The user's id required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User is not a leader: value: success: false error: 'User is not a leader [error-user-not-leader]' errorType: error-user-not-leader '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.removeModerator: post: tags: - Channels summary: Remove Channel Moderator description: | Remove the `moderator` role from a user in a channel. Permission required: `set-moderator`. ### Changelog | Version | Description | | ------- | ----------- | |0.49.4 | Added | operationId: post-api-v1-channels.removeModerator parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id userId: type: string description: The user's id required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: User is not a moderator: value: success: false error: 'User is not a moderator [error-user-not-moderator]' errorType: error-user-not-moderator details: method: removeRoomModerator '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.removeOwner: post: tags: - Channels summary: Remove Channel Owner description: | Remove the `owner` role from a user in a channel. Permission required:`set-owner`. ### Changelog | Version | Description | | ------- | ----------- | |0.49.4 | Added | operationId: post-api-v1-channels.removeOwner parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id userId: type: string description: The user's id required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.rename: post: tags: - Channels summary: Rename a Channel description: |- Change the name of a channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.48.0 | Added | operationId: pos-api-v1-channels.rename parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. name: type: string description: The new name of the channel. It can not be the same as the current name. required: - roomId - name examples: Example: value: roomId: WDuJLFkjwk6L7LdFC name: newName responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: channel: _id: ByehQjC44FwMeiLbX name: new-name t: c usernames: - testing1 msgs: 4 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:57:44.686Z' success: true '401': $ref: '#/components/responses/authorizationError' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: No permission: value: success: false error: 'Editing room is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: saveRoomSettings action: Editing_room /api/v1/channels.roles: get: tags: - Channels summary: Get Channel Roles description: |- Lists all user's roles in the channel. ### Changelog | Version | Description | | ------- | ----------- | |0.65.0 | Added | operationId: get-api-v1-channels.roles parameters: - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' responses: '200': description: OK content: application/json: schema: type: object properties: roles: type: array items: type: object properties: _id: type: string rid: type: string u: type: object properties: _id: type: string username: type: string name: type: string roles: type: array items: type: string success: type: boolean examples: Success: value: roles: - _id: rGNoXwYuZshq9FENQ rid: WDuJLFkjwk6L7LdFC u: _id: rbAXPnMktTFbNpwtJ username: roxie roles: - owner - _id: 64ef8a982c26843a68c1f7ae rid: WDuJLFkjwk6L7LdFC u: _id: 5fRTXMt7DMJbpPJfh username: test.test name: Testtest roles: - leader success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setAnnouncement: post: tags: - Channels summary: Set Channel Announcement description: |- Set an announcement for the channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.63.0 | Added | operationId: post-api-v1-channels.setAnnouncement parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id announcement: type: string description: The announcement to set for the channel. required: - roomId - announcement examples: Success: value: roomId: WDuJLFkjwk6L7LdFC announcement: Test out everything responses: '200': description: OK content: application/json: schema: type: object properties: announcement: type: string success: type: boolean examples: Example: value: announcement: Test out everything success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setCustomFields: post: tags: - Channels summary: Set Channel Custom Fields description: |- Sets the custom fields for a channel. Permission required: `edit-room`. See the Configure Custom Fields for Users document for configuration information. ### Changelog | Version | Description | | ------- | ----------- | |0.62.0 | Added | operationId: post-api-v1-channels.setCustomFields parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. Alternatively, enter the `roomName` parameter and provide the room's name as the value. customFields: type: object description: The custom fields to set for the channel. properties: organization: type: string required: - roomId - customFields - organization examples: Example: value: roomId: GENERAL customFields: organization: tra-la-la responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object properties: organization: type: string topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string announcement: type: string success: type: boolean examples: Success: value: channel: _id: WDuJLFkjwk6L7LdFC fname: new customFields: organization: tra-la-la topic: '' broadcast: false encrypted: false name: new t: c msgs: 72 usersCount: 45 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-04-05T22:34:38.936Z' ro: false default: false sysMes: true _updatedAt: '2023-09-27T05:24:34.363Z' lastMessage: _id: mBfC3sbNhfwcL4AQu rid: WDuJLFkjwk6L7LdFC msg: It should be good ts: '2023-09-16T07:37:59.691Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test _updatedAt: '2023-09-16T07:37:59.815Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: It should be good lm: '2023-09-16T07:37:59.691Z' announcement: Test out everything success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setDefault: post: tags: - Channels summary: Set Default Channel description: |- Set whether the channel is a default channel or not. All new users will automatically join this channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.66.0 | Added | operationId: post-api-v1-channels.setDefault parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. default: type: boolean description: Boolean of whether the room is default or not. required: - roomId - default examples: Example: value: roomId: ByehQjC44FwMeiLbX default: true responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string usernames: type: array items: type: string joinCodeRequired: type: boolean muted: type: array items: type: object default: type: boolean success: type: boolean examples: Example: value: channel: _id: ByehQjC44FwMeiLbX name: testing0 t: c msgs: 0 u: _id: aiPqNoGkjpNDiRx6d username: goose160 ts: '2017-01-05T18:02:50.754Z' ro: true sysMes: true _updatedAt: '2017-01-05T19:02:24.429Z' usernames: - goose160 - graywolf336 joinCodeRequired: true muted: [ ] default: true success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setDescription: post: tags: - Channels summary: Set Channel Description description: |- Set the description for a channel. Permission required: `edit-room`. ### Changelog | Version | Description | | ------- | ----------- | |0.48.4 | Added | operationId: post-api-v1-channels.setDescription parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. description: type: string description: The description to set for the channel. required: - roomId - description examples: Example: value: roomId: ByehQjC44FwMeiLbX description: Test out everything responses: '200': description: OK content: application/json: schema: type: object properties: description: type: string success: type: boolean examples: Success: value: description: Testing the room success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setJoinCode: post: tags: - Channels summary: Set Channel Join Code description: |- Set the code required to join the channel. If it is set, users must use the join code to successfully join the channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.49.0 | Added | operationId: post-api-v1-channels.setJoinCode parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. joinCode: type: string description: The join code that will be required for any user to join this channel. required: - roomId - joinCode examples: Example: value: roomId: ByehQjC44FwMeiLbX joinCode: 87hsyi9 responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string fname: type: string customFields: type: object properties: organization: type: string topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string announcement: type: string description: type: string joinCodeRequired: type: boolean success: type: boolean examples: Success: value: channel: _id: WDuJLFkjwk6L7LdFC fname: new customFields: organization: tra-la-la topic: '' broadcast: false encrypted: false name: new t: c msgs: 73 usersCount: 45 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-04-05T22:34:38.936Z' ro: false default: true sysMes: true _updatedAt: '2023-09-27T05:40:39.687Z' lastMessage: _id: mBfC3sbNhfwcL4AQu rid: WDuJLFkjwk6L7LdFC msg: It should be good ts: '2023-09-16T07:37:59.691Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test _updatedAt: '2023-09-16T07:37:59.815Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: It should be good lm: '2023-09-16T07:37:59.691Z' announcement: Test out everything description: Testing the room joinCodeRequired: true success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setPurpose: post: tags: - Channels summary: Set Channel Purpose description: |- Set the purpose or description of the channel. It is the same as Set Channel Description. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.48.0 | Added | operationId: post-api-v1-channels.setPurpose parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id purpose: type: string description: The description to set for the channel. required: - roomId - purpose examples: Example: value: roomId: WDuJLFkjwk6L7LdFC purpose: greetings responses: '200': description: OK content: application/json: schema: type: object properties: purpose: type: string success: type: boolean examples: Success: value: purpose: greetings success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setReadOnly: post: tags: - Channels summary: Set Channel ReadOnly description: |- Set a channel to be read-only or not. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | |0.49.0 | Added | operationId: post-api-v1-channels.setReadOnly parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel ID. readOnly: type: boolean description: Boolean of whether the room is read-only or not. required: - roomId - readOnly examples: Example: value: roomId: ByehQjC44FwMeiLbX readOnly: true responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string usernames: type: array items: type: string joinCodeRequired: type: boolean muted: type: array items: type: object success: type: boolean examples: Success: value: channel: _id: ByehQjC44FwMeiLbX name: testing0 t: c msgs: 0 u: _id: aiPqNoGkjpNDiRx6d username: goose160 ts: '2017-01-05T18:02:50.754Z' ro: true sysMes: true _updatedAt: '2017-01-05T19:02:24.429Z' usernames: - goose160 - graywolf336 joinCodeRequired: true muted: [ ] success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setTopic: post: tags: - Channels summary: Set Channel Topic description: |- Set the topic for a channel. Permission required: `edit-room`. ### Changelog | Version | Description | | ------- | ----------- | |0.13.0 | Added | operationId: post-api-v1-channels.setTopic parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. topic: type: string description: The channel's topic required: - roomId - topic examples: Example: value: roomId: WDuJLFkjwk6L7LdFC topic: Discuss all of the testing responses: '200': description: OK content: application/json: schema: type: object properties: topic: type: string success: type: boolean examples: Success: value: topic: Discuss all of the testing success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.setType: post: tags: - Channels summary: Set Channel Type description: |- Set the channel type. The channel type can be either `c` (public) or `p` (private). The following permissions are required: * `create-c`: To change a private group to a public channel. * `create-p`: To change a public channel to a private room. For ABAC-managed private rooms, changing the type from `p` to `c` is rejected with `error-action-not-allowed`. When the type changes to `c` (public) and the room has ABAC attributes, all ABAC attributes on the room are cleared as part of the conversion. ### Changelog | Version | Description | | ------- | ----------- | | 8.5.0 | Added ABAC behavior for `p` -> `c`: ABAC-managed private rooms are rejected, and successful conversions to public clear room ABAC attributes. | | 0.49.0 | Added | operationId: post-api-v1-channels.setType parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: description: '' content: application/json: schema: type: object properties: roomId: type: string description: The channel's ID. Alternatively, enter the `channelName` parameter and provide the channel's name as the value. type: type: string description: |- The channel's type. The type of room this channel should be, either c or p. `c` is for channel and `p` is for private. required: - roomId - type examples: Example: value: roomId: WDuJLFkjwk6L7LdFC type: p responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string usernames: type: array items: type: string joinCodeRequired: type: boolean muted: type: array items: type: object success: type: boolean examples: Success: value: channel: _id: ByehQjC44FwMeiLbX name: testing0 t: p msgs: 0 u: _id: aiPqNoGkjpNDiRx6d username: goose160 ts: '2017-01-05T18:02:50.754Z' ro: false sysMes: true _updatedAt: '2017-01-05T19:02:24.429Z' usernames: - goose160 - graywolf336 joinCodeRequired: true muted: [ ] success: true '401': $ref: '#/components/responses/authorizationError' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: ABAC-managed room conversion blocked: value: success: false error: 'Changing an ABAC managed private room to public is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: saveRoomSettings action: Change_Room_Type /api/v1/channels.unarchive: post: tags: - Channels summary: Unarchive a Channel description: |- Unarchive a channel. Permission required: `unarchive-room` ### Changelog | Version | Description | | ------- | ----------- | |0.48.0 | Added | operationId: post-api-v1-channels.unarchive parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The channel ID that you want to unarchive. responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.getAllUserMentionsByChannel: get: tags: - Channels summary: Get User Mentions in a Channel description: |- Get all the mentions of the authenticated user in a channel. ### Changelog | Version | Description| | ------- | -----------| |0.63.0 | Added | operationId: get-api-v1-channels.getAllUserMentionsByChannel parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/RoomId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: OK content: application/json: schema: type: object properties: mentions: type: array items: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object properties: _id: type: string username: type: string name: type: string type: type: string channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: object properties: type: type: string value: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: mentions: - _id: mPmJ6cPAazzphJmGe rid: 6513afeda2f73c7460e18c86 msg: '@roxie' ts: '2023-09-27T20:32:58.994Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-27T20:32:59.171Z' urls: [ ] mentions: - _id: rbAXPnMktTFbNpwtJ username: roxie name: test test type: user channels: [ ] md: - type: PARAGRAPH value: - type: MENTION_USER value: type: PLAIN_TEXT value: roxie count: 1 offset: 0 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.getIntegrations: get: tags: - Channels summary: Get Channel Integrations description: |- Retrieves the integrations that the channel has. The endpoint requires at least one of the following integration permissions: - `manage-incoming-integrations` - `manage-own-incoming-integrations` - `manage-outgoing-integrations` - `manage-own-outgoing-integrations`. It will return the integrations based on the user's permission. ### Changelog | Version | Description | | ------- | -------------------------------------------------- | | 1.1.0 | Separate permissions in `incoming` and `outgoing`. | | 0.49.0 | Added | operationId: get-api-v1-channels.getIntegrations parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/RoomId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/count' responses: '200': description: OK content: application/json: schema: type: object properties: integrations: type: array items: type: object properties: _id: type: string enabled: type: boolean username: type: string alias: type: string avatar: type: string name: type: string triggerWords: type: array items: type: string urls: type: array items: type: string token: type: string script: type: string scriptEnabled: type: boolean impersonateUser: type: boolean scriptCompiled: type: string scriptError: type: string type: type: string userId: type: string channel: type: array items: type: object _createdAt: type: string _createdBy: type: object properties: username: type: string _id: type: string _updatedAt: type: string success: type: boolean examples: Example: value: integrations: - _id: WMQDChpnYTRmFre9h enabled: true username: rocket.cat alias: Guggy avatar: 'http://res.guggy.com/logo_128.png' name: Guggy triggerWords: - '!guggy' - guggy - gif+ urls: - 'http://text2gif.guggy.com/guggify' token: 8DFS89DMKLWEN script: |- const config = {color: '#ffffff'};class Script{} scriptEnabled: true impersonateUser: false scriptCompiled: 'function _classCallCheck(instance,Constructor){if(!(instance instanceof Constructor));' scriptError: "" type: webhook-outgoing userId: rocket.cat channel: [ ] _createdAt: '2017-01-05T17:06:05.660Z' _createdBy: username: graywolf336 _id: R4jgcQaQhvvK6K3iY _updatedAt: '2017-01-05T17:06:05.660Z' success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/channels.convertToTeam: post: tags: - Channels summary: Convert Channel to Team description: |- Convert a channel to a team. Permissions required: `create-team`, `edit-room`. Both permissions are checked against the target channel, whether you identify it by `channelId` or `channelName`. ### Changelog | Version | Description | | ------- | ----------- | | 8.7.0 | Enforced room permission checks regardless of whether the channel is identified by ID or name. | | 3.13.0 | Added | operationId: post-api-v1-channels.convertToTeam parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: channelId: type: string description: The channel's ID. Provide either `channelId` or `channelName`, but not both. channelName: type: string description: The channel's name. Provide either `channelName` or `channelId`, but not both. oneOf: - required: - channelId - required: - channelName examples: Convert channel by ID: value: channelId: 6513afeda2f73c7460e18c86 Convert channel by name: value: channelName: messages responses: '200': description: OK content: application/json: schema: type: object properties: team: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string success: type: boolean examples: Channel converted to team: value: team: _id: 65149c7ea2f73c7460e18cab name: messages type: 0 createdAt: '2023-09-27T21:19:58.972Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: roxie _updatedAt: '2023-09-27T21:19:58.972Z' roomId: 6513afeda2f73c7460e18c86 success: true '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing channel permissions: value: success: false error: unauthorized /api/v1/rooms.saveNotification: post: tags: - Rooms summary: Set Room Notifications description: |- Set the notification settings of a specific room. ### Changelog | Version | Description | | ------- | ----------- | |0.63.0 | Added | operationId: post-api-v1-rooms.saveNotification parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The channel's id notifications: type: object description: The object that contains the following parameters. properties: desktopNotifications: type: string description: |- The value for desktop notifications. The options are: - nothing - mentions - all - default disableNotifications: type: string description: |- The value to disable/enable channel's notifications. The options are: - 0 - 1 emailNotifications: type: string description: |- The value for email notifications. The options are: - nothing - mentions - all - default audioNotificationValue: type: string description: The value for audio notification sound. desktopNotificationDuration: type: string description: The value for desktop notification duration. audioNotifications: type: string description: |- The value for audio notifications. The options are: - nothing - mentions - all - default unreadAlert: type: string description: |- The value for unread alerts notifications. The options are: - nothing - mentions - all - default hideUnreadStatus: type: string description: |- The value to disable/enable number of unread messages. The options are: - 0 - 1 mobilePushNotifications: type: string description: |- The value for mobile push notifications. The options are: - nothing - mentions - all - default required: - roomId - notifications examples: Example: value: roomId: 5of4weEXaH7yncxz9 notifications: desktopNotifications: all disableNotifications: 0 emailNotifications: nothing audioNotificationValue: beep desktopNotificationDuration: '2' audioNotifications: all unreadAlert: nothing hideUnreadStatus: 0 mobilePushNotifications: mentions responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.saveDraft: post: tags: - Rooms summary: Save Room Draft description: |- Save or clear the authenticated user's message draft for a room or an existing thread. The user must have a subscription to the room. To save a room draft, omit `tmid`. To save a thread draft, provide the ID of the thread's main message in `tmid`. Send an empty `draft` to clear the corresponding room or thread draft. The draft cannot exceed the workspace's `Message_MaxAllowedSize` setting. ### Changelog | Version | Description | | ------- | ----------- | | 8.8.0 | Added the optional `tmid` parameter to save thread drafts | | 8.5.0 | Added | operationId: post-api-v1-rooms.saveDraft parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: type: object properties: rid: type: string minLength: 1 description: The room ID. draft: type: string description: The draft text. Send an empty string to clear the draft. tmid: type: string minLength: 1 pattern: '^[^.$]+$' description: The ID of the thread's main message. Omit this parameter to save or clear the main room draft. required: - rid - draft additionalProperties: false examples: Save room draft: value: rid: GENERAL draft: Remember to share the report Save thread draft: value: rid: GENERAL draft: I will check this and reply tmid: 7aDSXtjMA3KPLxLjt Clear thread draft: value: rid: GENERAL draft: '' tmid: 7aDSXtjMA3KPLxLjt responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid subscription: value: success: false error: 'Invalid subscription [error-invalid-subscription]' errorType: error-invalid-subscription Draft exceeds maximum size: value: success: false error: error-message-size-exceeded '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.adminRooms: get: tags: - Rooms summary: Get All Room Admins description: |- Retrieves all rooms and admin information. Permission required: `view-room-administration` ### Changelog | Version | Description | | ------- |--------------| | 8.7.0 | Restored `customFields` in the response | | 2.4.0 | Added | operationId: get-api-v1-rooms.adminRooms parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: types in: query description: |- The room types. The possible room types are: - `d`: Direct messages - `c`: Public channel - `p`: Private channel - `discussions`: Team or channel discussions - `teams`: Workspace teams - `l`: Livechat - `v`: Omnichannel VoIP rooms schema: type: array items: type: string - name: filter in: query description: The rooms name schema: type: string - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - schema: type: string in: query name: sort description: |- Sort the channels in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON object. The options are as follows: * `ts`: Sort by creation timestamp. For example, `sort={"ts":-1}` * `usersCount`: Sort by number of users. For example, `sort={"usersCount":1}` * `name`: Sort by the room name. For example, `sort={"name":1}` responses: '200': description: OK content: application/json: schema: type: object properties: rooms: type: array items: type: object properties: _id: type: string fname: type: string description: type: string broadcast: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ro: type: boolean default: type: boolean topic: type: string announcement: type: string customFields: type: object description: The custom fields set on the room. count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: rooms: - _id: 654c9d1ca2f73c7460e1918b fname: animalGeography topic: '' broadcast: false name: animalGeography t: p msgs: 4 usersCount: 1 u: _id: CkCPNcvsvCDfmWLqC username: kim.jane name: kim.jane ro: false default: false customFields: department: engineering priority: high count: 1 offset: 0 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.cleanHistory: post: tags: - Rooms summary: Clear Room History description: |- Cleans up a room by removing messages from the provided time range. For details, see the Prune messages from a room section. Permission required: `clean-channel-history` ### Changelog | Version | Description | | ------- | ---------------------- | | 0.64.0 | Added | | 0.67.0 | Added fields `limit`, `excludePinned`, `filesOnly` and `users` | operationId: get-api-v1-rooms.cleanHistory parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The room ID. latest: type: string description: The end of time range of messages. oldest: type: string description: The start of the time range of messages. inclusive: type: boolean description: 'Whether messages which land on the latest and oldest dates should be included. By default, the value is false.' excludePinned: type: boolean description: 'Whether pinned messages should be deleted. By default, the value is false.' filesOnly: type: boolean description: 'Whether to only delete files and keep messages intact. By default, the value is false.' users: type: array items: type: string description: 'Specific set of users whose content to delete. By default, the value is [], that is, everyone.' limit: type: integer description: 'The amount of messages to prune. By default, the value is 0 (all).' ignoreDiscussion: type: boolean description: 'Determines if messages from discussions should be pruned. By default, the value is true.' ignoreThreads: type: boolean description: 'Determines if messages from threads should be pruned. By default, the value is true.' required: - roomId - latest - oldest examples: Example: value: roomId: roomId latest: '2016-12-09T13:42:25.304Z' oldest: '2016-08-30T13:42:25.304Z' responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.history: get: tags: - Rooms summary: Get Room History description: |- Returns the message history of a room of any type, with cursor-based pagination. Hidden system messages are excluded. When the **Allow Anonymous Read** (`Accounts_AllowAnonymousRead`) setting is enabled, public channels can be read without authentication. This endpoint replaces the deprecated `loadHistory`, `loadNextMessages`, and `loadSurroundingMessages` Realtime API methods, which remain available until 9.0.0. Permission required: `preview-c-room` (only to read a public channel you have not joined) ### Changelog | Version | Description | | ------- | ----------- | | 8.9.0 | Added | operationId: get-api-v1-rooms.history parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: roomId in: query description: |- The room ID. You must have access to the room. required: true schema: type: string example: 6GFJ3tbmHiyHbahmC - name: count in: query description: |- The number of messages to return. The default is 20. The value is capped by the **Max Record Amount** (`API_Upper_Count_Limit`) setting. required: false schema: type: integer minimum: 1 default: 20 example: 20 - name: previous in: query description: |- The `cursor.previous` value from a previous response. Returns the messages older than that position. If `cursor.previous` is `null`, there are no older messages. Cannot be combined with `next` or `aroundId`. required: false schema: type: string example: '1790157600000' - name: next in: query description: |- The `cursor.next` value from a previous response. Returns the messages newer than that position. If `cursor.next` is `null`, there are no newer messages. Cannot be combined with `previous` or `aroundId`. required: false schema: type: string example: '1790157900000' - name: aroundId in: query description: |- The ID of a message in the room. It loads messages centered around that message, including the message itself. Use it to jump to a specific message, such as a quoted message or a search result. Cannot be combined with `next` or `previous`. required: false schema: type: string example: Xq8sLpW3nZr2TmKeA - name: lastSeen in: query description: |- An ISO 8601 date-time for the user's last-read position. It does not limit the returned messages. When the oldest returned message is newer than this value, the response includes `firstUnread` and `unreadNotLoaded`. required: false schema: type: string format: date-time example: '2026-09-23T09:00:00.000Z' - name: showThreadMessages in: query description: |- Whether to include thread replies that were not also sent to the room. The default is `true`. required: false schema: type: boolean default: true example: true responses: '200': description: OK content: application/json: schema: type: object properties: messages: type: array description: The messages, ordered newest first. items: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string mentions: type: array items: type: object channels: type: array items: type: object cursor: type: object properties: next: type: string nullable: true description: The cursor for newer messages, or `null` if there are none. previous: type: string nullable: true description: The cursor for older messages, or `null` if there are none. firstUnread: type: object description: The oldest unread message that was not loaded in this response. Returned only when `lastSeen` is provided and unread messages exist beyond the returned messages. unreadNotLoaded: type: integer description: The number of unread messages newer than `lastSeen` that were not loaded in this response. success: type: boolean examples: Success Example: value: messages: - _id: Xq8sLpW3nZr2TmKeA rid: 6GFJ3tbmHiyHbahmC msg: The release checklist is ready for review. ts: '2026-09-23T10:05:00.000Z' u: _id: rbAXPnMktTFbNpwtJ username: dana.reyes name: Dana Reyes _updatedAt: '2026-09-23T10:05:00.000Z' mentions: [] channels: [] - _id: Bv5nTq7RkWz3YpLcD rid: 6GFJ3tbmHiyHbahmC msg: Thanks, I will take a look this afternoon. ts: '2026-09-23T10:00:00.000Z' u: _id: kP3wQz8LmNvT5rXyB username: sam.okafor name: Sam Okafor _updatedAt: '2026-09-23T10:00:00.000Z' mentions: [] channels: [] cursor: next: null previous: '1790157600000' unreadNotLoaded: 0 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Cursor Conflict: value: success: false error: 'Only one of "next", "previous" and "aroundId" can be provided [error-cursor-conflict]' errorType: error-cursor-conflict Invalid Cursor: value: success: false error: 'Invalid pagination cursor [error-invalid-cursor]' errorType: error-invalid-cursor '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden. You cannot access the room, or the room is a public channel that you have not joined and you do not have the `preview-c-room` permission. content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: unauthorized '404': description: Not Found. The room does not exist, or the message in `aroundId` is not a visible message in the room. content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Not Found: value: success: false error: Resource not found /api/v1/rooms.info: get: tags: - Rooms summary: Get Room Information description: |- Retrieves the information about the room. ### Changelog | Version | Description | | ------- | ----------- | |0.72.0 | Added | operationId: get-api-v1-rooms.info parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/fields' responses: '200': description: |- OK The response includes the following objects: * `parent`: Represents the parent of a room. For discussions, this is the room where the discussion was created, identified by `prid`. For rooms inside a team, the parent will be the team's main room, identified by `team.roomId`. For other rooms, this property is undefined. * `team`: Represents the team a room is part of. For rooms inside a team, this is the team identified by the `teamId` property. For everything else, this is undefined. content: application/json: schema: type: object properties: room: type: object properties: _id: type: string ts: type: string t: type: string name: type: string usernames: type: array items: type: object properties: { } msgs: type: integer usersCount: type: integer _updatedAt: type: string u: type: object properties: _id: type: string username: type: string name: type: string default: type: boolean lastMessage: type: object properties: _id: type: string t: type: string rid: type: string ts: type: string msg: type: string alias: type: string nullable: true attachments: type: array items: type: object file: type: object properties: _id: type: string name: type: string type: type: string u: type: object properties: _id: type: string username: type: string name: type: string groupable: type: boolean drid: type: string _updatedAt: type: string lm: type: string success: type: boolean examples: Success: value: room: _id: 66ed2dba40141d95f32c292b fname: new-channel _updatedAt: '2024-09-20T12:29:08.284Z' customFields: { } topic: '' broadcast: false encrypted: false name: new-channel t: p msgs: 3 usersCount: 2 u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat ts: '2024-09-20T08:09:30.417Z' ro: false teamId: 66c82d78237405fc05fc1ef1 default: false sysMes: true lastMessage: _id: xZhJfE4rmaosjHZCe rid: 66ed2dba40141d95f32c292b msg: testing alias: null ts: '2024-09-20T12:27:53.356Z' u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat _updatedAt: '2024-09-20T12:27:53.397Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: testing lm: '2024-09-20T12:27:53.356Z' team: _id: 66c82d78237405fc05fc1ef1 name: test-team type: 0 roomId: 66c82d78237405fc05fc1eef parent: _id: 66c82d78237405fc05fc1eef fname: test-team name: test-team t: c success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-roomid-param-not-provided]' errorType: error-roomid-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.getDiscussions: get: tags: - Rooms summary: Get Room Discussions description: |- Get all discussions of a room. ### Changelog | Version | Description | | ------- | --------------| | 1.0.0 | Added | operationId: get-api-v1-rooms.getDiscussions parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/offset' - schema: type: string in: query name: sort description: |- Sort the channels in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON object. The options are as follows: * `fname`: Sort by discussion name. For example, `sort={"fname":1}` (this is the default sorting mechanism). * `ts`: Sort by creation timestamp. For example, `sort={"ts":-1}` * `usersCount`: Sort by number of users. For example, `sort={"usersCount":1}` responses: '200': description: OK content: application/json: schema: type: object properties: discussions: type: array items: type: object properties: _id: type: string fname: type: string _updatedAt: type: string topic: type: string prid: type: string encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string name: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: discussions: - _id: 6514d34ea2f73c7460e18cb4 fname: test-discussion _updatedAt: '2023-09-28T01:14:04.275Z' topic: general prid: GENERAL encrypted: false name: M75nSgA3uYsnTbKRu t: c msgs: 1 usersCount: 1 u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test ts: '2023-09-28T01:13:50.574Z' ro: false default: false sysMes: true lastMessage: _id: pnm4kh84HfncDEZj7 rid: 6514d34ea2f73c7460e18cb4 msg: 'Hi guys , this is for SWE team' ts: '2023-09-28T01:14:04.119Z' u: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test _updatedAt: '2023-09-28T01:14:04.233Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: 'Hi guys , this is for SWE team' lm: '2023-09-28T01:14:04.119Z' count: 1 offset: 0 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.get: get: tags: - Rooms summary: Get Rooms description: |- Get all opened rooms (all joined public & private channels and all DMs) of the authenticated user. ### Changelog | Version | Description | | ------- | --------------| | 0.72.0 | Added | operationId: get-api-v1-rooms.get parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: updatedSince in: query description: 'A date as an ISO string. When you provide the `updatedSince` query parameter, then the update and remove in the response will contain only those updated and removed since the specified date and time.' schema: type: string example: '2017-11-25T15:08:17.248Z' responses: '200': description: OK content: application/json: schema: type: object properties: update: type: array items: type: object properties: _id: type: string ts: type: string t: type: string name: type: string usernames: type: array items: type: string msgs: type: integer usersCount: type: integer _updatedAt: type: string u: type: object properties: _id: type: string username: type: string name: type: string default: type: boolean lastMessage: type: object properties: _id: type: string t: type: string rid: type: string ts: type: string msg: type: string alias: type: string nullable: true attachments: type: array items: $ref: '#/components/schemas/Attachment' file: type: object properties: _id: type: string name: type: string type: type: string u: type: object properties: _id: type: string username: type: string name: type: string groupable: type: boolean drid: type: string _updatedAt: type: string urls: type: array items: type: object properties: url: type: string meta: type: object properties: { } mentions: type: array items: type: object properties: { } channels: type: array items: type: object properties: { } md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string items: type: object properties: type: type: string value: type: string src: type: object properties: type: type: string value: type: string label: type: array items: type: object properties: type: type: string value: type: string lm: type: string uids: type: array items: type: string ro: type: boolean sysMes: type: boolean remove: type: array items: type: object properties: { } success: type: boolean examples: Success: value: update: - _id: GENERAL ts: '2024-02-14T14:34:49.365Z' t: c name: general usernames: [ ] msgs: 55 usersCount: 36 _updatedAt: '2024-07-16T08:49:34.732Z' u: _id: rocket.cat username: rocket.cat name: Rocket.Cat default: true lastMessage: _id: '668fc2bbffe932842327c1ff' t: discussion-created rid: 'GENERAL' ts: '2024-07-11T11:32:11.220Z' msg: Discussion u: _id: 5m4hjvzCTRCqwPrD2 username: Rama name: Raghav Ram groupable: false drid: 668fc2bbffe932842327c1fd _updatedAt: '2024-07-11T11:32:11.220Z' lm: '2024-07-11T11:32:11.220Z' - _id: WbYJfC5kTArcECGkpfZ3bvXC72pobjFPLJ t: d usernames: - user2 - user1 usersCount: 2 msgs: 2 ts: '2024-07-10T13:48:14.998Z' uids: - WbYJfC5kTArcECGkp - fZ3bvXC72pobjFPLJ default: false ro: false sysMes: true _updatedAt: '2024-07-10T13:48:28.300Z' lastMessage: _id: 'XHjLcN3pCe8snaoTm' rid: 'WbYJfC5kTArcECGkpfZ3bvXC72pobjFPLJ' msg: 'again' ts: '2024-07-10T13:48:28.262Z' u: _id: fZ3bvXC72pobjFPLJ username: user1 name: user1 _updatedAt: '2024-07-10T13:48:28.296Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: again lm: '2024-07-10T13:48:28.262Z' - _id: fZ3bvXC72pobjFPLJrocket.cat t: d usernames: - user1 - rocket.cat usersCount: 2 msgs: 15 ts: '2024-02-21T02:00:01.657Z' uids: - fZ3bvXC72pobjFPLJ - rocket.cat default: false ro: false sysMes: true _updatedAt: '2024-07-17T02:00:05.203Z' lastMessage: rid: fZ3bvXC72pobjFPLJrocket.cat msg: |- *Update your Rocket.Chat* New version available (6.10.0) https://github.com/RocketChat/Rocket.Chat/releases/tag/6.10.0 ts: '2024-07-17T02:00:05.161Z' u: _id: rocket.cat username: rocket.cat name: Rocket.Cat _id: c4PzLLTy4fDSCmm4F _updatedAt: '2024-07-17T02:00:05.198Z' urls: - url: 'https://github.com/RocketChat/Rocket.Chat/releases/tag/6.10.0' meta: { } mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: BOLD value: - type: PLAIN_TEXT value: Update your Rocket.Chat - type: PARAGRAPH value: - type: PLAIN_TEXT value: New version available (6.10.0) - type: PARAGRAPH value: - type: LINK value: src: type: PLAIN_TEXT value: 'https://github.com/RocketChat/Rocket.Chat/releases/tag/6.10.0' label: - type: PLAIN_TEXT value: 'https://github.com/RocketChat/Rocket.Chat/releases/tag/6.10.0' lm: '2024-07-17T02:00:05.161Z' remove: [ ] success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.join: post: tags: - Rooms summary: Join a Room description: |- Join a room of any type, including public channels, private groups, and discussions. Unlike the channels.join endpoint, which only joins public channels, this endpoint applies to all kinds of rooms. ### Changelog | Version | Description | | ------------ | ----------- | | 8.6.0 | Added | operationId: post-api-v1-rooms.join parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: oneOf: - type: object properties: roomId: type: string description: The ID of the room to join. Provide either `roomId` or `roomName`. example: ByehQjC44FwMeiLbX joinCode: type: string description: |- The join code of the room. Rooms can be password-protected. In that case, users must enter the password for access. The join code isn't needed if the user has the `join-without-join-code` permission. example: '1234' required: - roomId additionalProperties: false - type: object properties: roomName: type: string description: The name of the room to join. Provide either `roomId` or `roomName`. example: general joinCode: type: string description: |- The join code of the room. Rooms can be password-protected. In that case, users must enter the password for access. The join code isn't needed if the user has the `join-without-join-code` permission. example: '1234' required: - roomName additionalProperties: false examples: Join by room ID: value: roomId: ByehQjC44FwMeiLbX joinCode: '1234' Join by room name: value: roomName: general responses: '200': description: OK content: application/json: schema: type: object properties: room: type: object properties: _id: type: string name: type: string fname: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Example: value: room: _id: ByehQjC44FwMeiLbX name: general fname: general t: c msgs: 8 usersCount: 2 u: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test ts: '2026-01-16T12:00:04.783Z' ro: false sysMes: true default: true _updatedAt: '2026-01-16T12:06:30.426Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid params: value: success: false error: 'Match error: Missing key ''roomId''' errorType: error-invalid-params Room not found: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any channel [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.leave: post: tags: - Rooms summary: Leave Room description: |- Leave a room. The following permissions are required: * `leave-c`: To leave a public room. * `leave-p`: To leave private room. ### Changelog | Version | Description | | ------- | --------------| | 0.72.0 | Added | operationId: post-api-v1-rooms.leave parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The room ID that you want to leave. responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.delete: post: tags: - Rooms summary: Delete Room description: |- Delete a room from the workspace. The following permissions are required: * `delete-c`: To delete a public room. * `delete-d`: To delete direct messages. * `delete-p`: To delete private rooms. * `delete-team`: To delete a team. * `delete-team-channel`: To delete a channel within a team, also requires the `delete-c` permission. * `delete-team-group`: To delete a private channel within a team, also requires the `delete-p` permission. > You can't use this endpoint to delete a team's main room. Use [Delete a Team endpoint](https://developer.rocket.chat/apidocs/delete-a-team) instead. ### Changelog | Version | Description | | ------- | --------------| | 5.4.0 | Added | operationId: get-api-v1-rooms.delete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - roomId properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The room ID that you want to delete. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: 'Example 1: Missing roomId': value: success: false error: The 'roomId' param is required 'Example 2: Missing Permission': value: success: true error: string 'Example 3: Cannot Delete Team Channel': value: success: false error: 'Cannot delete a team channel [error-cannot-delete-team-channel]' errorType: error-cannot-delete-team-channel details: method: eraseRoom '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.favorite: post: tags: - Rooms summary: Favorite/Unfavourite a Room description: |- Mark/Unmark a room as favourite. ### Changelog | Version | Description | | ------- | --------------| | 0.64.0 | Added | operationId: post-api-v1-rooms.favorite parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The room ID. Alternatively, enter the `roomName` parameter and provide the room's name as the value. You must be a member of the room. favorite: type: boolean description: A boolean to mark the room as favourite or not. required: - roomId - favorite examples: Example: value: roomId: GENERAL favorite: true responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.autocomplete.availableForTeams: get: tags: - Rooms summary: Autocomplete Room Name for Team description: Autocompletes room name available for conversion to team. operationId: get-api-v1-rooms.autocomplete.availableForTeams parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: name in: query description: The name of the room required: true schema: type: string example: data-loss-prevention responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string fname: type: string name: type: string t: type: string success: type: boolean examples: Match error: value: items: - _id: siyr2oWQJBjQjhLwr fname: try name: try t: c success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.autocomplete.channelAndPrivate: get: tags: - Rooms summary: Autocomplete Room Name for Private and Public Rooms operationId: get-api-v1-rooms.autocomplete.channelAndPrivate parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: '{"name":"ran"}' in: query name: selector required: true description: The term to be completed. It only applies to room name. responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string fname: type: string name: type: string t: type: string success: type: boolean examples: Success: value: items: - _id: 664f0d525df46832f75b1860 fname: rancher name: rancher t: p - _id: 6630e94ad2226209149c67e2 fname: random name: random t: c - _id: 664f148f5df46832f75b18b2 fname: ranmowe name: ranmowe t: p success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Selector Param Required: value: success: false error: The 'selector' param is required '401': $ref: '#/components/responses/authorizationError' description: |- List the public and private rooms whose names match a given string, excluding discussions, DMs, and omnichannel rooms. The endpoint is valuable when performing search operations. It returns only rooms that the user belongs to. /api/v1/rooms.autocomplete.adminRooms: get: tags: - Rooms summary: Admin Autocomplete Room Name for Private and Public Rooms operationId: get-api-v1-rooms.autocomplete.adminRooms parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: '{"name":"ran"}' in: query name: selector required: true description: The term to be completed. It applies to room name and display name. responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string fname: type: string name: type: string t: type: string success: type: boolean examples: Success: value: items: - _id: 664f0d815df46832f75b1877 fname: rangig name: Ch9xkYwGHnsLe7CQR t: c - _id: 664f0d525df46832f75b1860 fname: rancher name: rancher t: p - _id: 6630e94ad2226209149c67e2 fname: random name: random t: c success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Selector Param Required: value: success: false error: The 'selector' param is required '401': $ref: '#/components/responses/authorizationError' description: |- List public and private rooms whose names match a given string, excluding DMs, and omnichannel rooms. This endpoint is valuable when performing search operations. Only workspace administrators can use it. Any one of the following permissions are required: * `view-room-administration` * `can-audit` parameters: [ ] /api/v1/rooms.adminRooms.getRoom: get: tags: - Rooms summary: Get Admin of Room description: |- Retrieves the admin of a room. Permission required: `view-room-administration` ### Changelog | Version | Description | | ------- | --------------- | | 8.7.0 | Restored `customFields` in the response | | 2.4.0 | Added | operationId: get-api-v1-rooms.adminRooms.getRoom parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: rid in: query description: 'The room ID.' schema: type: string example: 654c9d1ca2f73c7460e1918b required: true responses: '200': description: OK content: application/json: schema: type: object properties: _id: type: string name: type: string fname: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ro: type: boolean default: type: boolean customFields: type: object description: The custom fields set on the room. success: type: boolean examples: Success: value: _id: ukFsHiySDhMkQyyyF name: freightwave fname: freightwave t: p msgs: 4 usersCount: 1 u: _id: Gd6iymRZBK4C6wqHN username: bruno.raymundo ro: false default: false customFields: department: engineering priority: high success: true '401': $ref: '#/components/responses/authorizationError' '403': $ref: '#/components/responses/forbiddenError' /api/v1/rooms.saveRoomSettings: post: tags: - Rooms summary: Save Room Settings description: |- Updates the settings of an existing room. For ABAC-managed rooms, the following guardrails apply: - Changing `roomAnnouncement`, `roomTopic`, or `roomDescription` is rejected with `error-action-not-allowed`. - Setting `default: true` on an ABAC-managed room is rejected with `error-action-not-allowed`. - Changing `roomType` from `p` to `c` is rejected with `error-action-not-allowed`. The same guard applies to private rooms in ABAC-managed private teams. - When `roomType` changes to `c` (public) and conversion is allowed, existing room ABAC attributes are cleared as part of the conversion. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ------------| | 8.5.0 | Added ABAC guardrails: announcement, topic, description, default flag, and conversion to public are blocked on ABAC-managed rooms. | | 3.13.0 | Added | operationId: post-api-v1-rooms.saveRoomSettings parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: rid: type: string description: The room ID. roomName: type: string description: The name of the room. roomDescription: type: string description: The description of the room. roomAvatar: type: string description: The base64 image. featured: type: boolean description: Whether the room is featured or not. roomTopic: type: string description: The topic of the room. roomAnnouncement: type: string description: The announcement of the room. roomCustomFields: type: object description: An object of the custom fields of the room. roomType: type: string description: The type of the room. It could be `c` for public rooms or `p` for private rooms. readOnly: type: boolean description: Whether the room is read-only or not. reactWhenReadOnly: type: boolean description: Whether users can react when the room is read-only. systemMessages: type: array items: type: string description: The system messages that the room supports. default: type: boolean description: Whether the room is the default room or not. joinCode: type: string description: The join code of the room. streamingOptions: type: object description: The streaming options of the room. retentionEnabled: type: boolean description: Whether retention is enabled for the room or not. retentionMaxAge: type: string description: The maximum age (in days) of messages to be retained in the room. retentionExcludePinned: type: boolean description: Whether to exclude pinned messages from retention or not. retentionFilesOnly: type: boolean description: Whether to retain only files in the room or not. retentionIgnoreThreads: type: boolean description: Whether to ignore threads when retaining messages or not. retentionOverrideGlobal: type: boolean description: Whether to override the global retention settings for the room or not. encrypted: type: boolean description: Whether the room is encrypted or not. favorite: type: object description: The favorite settings of the room. Whether the room is marked as favorite and whether it is set as the default room. sidepanel: type: object description: List the team's channels or discussions to be displayed in the sidepanel. properties: items: type: array description: The options are `discussions` and `channels`. items: type: string example: '["discussions", "channels"]' required: - rid examples: Example: value: rid: JZ8Y2dLfYhsg323Rf roomName: Test-Save-Room roomDescription: This is a test room. responses: '200': description: OK content: application/json: schema: type: object properties: rid: type: string success: type: boolean examples: Success: value: rid: JZ8Y2dLfYhsg323Rf success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: Invalid room: value: success: false error: 'Invalid room [error-invalid-room]' errorType: error-invalid-room ABAC-managed room type conversion blocked: value: success: false error: 'Changing an ABAC managed private room to public is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: saveRoomSettings action: Change_Room_Type ABAC-managed room default blocked: value: success: false error: 'Setting an ABAC managed room as default is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: saveRoomSettings action: Viewing_room_administration '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.nameExists: parameters: [ ] get: summary: Check if Room Name Exists description: Check if the room name exists tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: exists: type: boolean success: type: boolean examples: Success: value: exists: true success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: roomName is required: value: success: false error: 'must have required property ''roomName'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-rooms.nameExists parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: test-room in: query name: roomName description: Enter the room name that you want to check. required: true /api/v1/rooms.changeArchivationState: post: tags: - Rooms summary: Change Room Archive State description: |- Archive or unarchive a room. Permissions required: * `archive-room`: To archive a room. * `unarchive-room`: To unarchive a room. ### Changelog | Version | Description | | ------- | ---------------- | | 3.3.0 | Added | operationId: post-api-v1-rooms.autocomplete.channelAndPrivate parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: rid: type: string description: The room Id. action: type: string description: It can either be archive or otherwise unarchived. required: - rid - action examples: Example: value: rid: iu7jtPAhvEeAS5tNq action: archive responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: Invalid Room: value: success: false error: 'Invalid room [error-invalid-room]' errorType: error-invalid-room details: method: unarchiveRoom '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.export: post: tags: - Rooms summary: Export Room description: | Export room messages to a file or email. When exporting to a file, the ZIP file is stored in the `/tmp` directory on the Rocket.Chat server, and its details are recorded in the `rocketchat_user_data_files` collection in MongoDB. Permission required: `mail-messages` ### Changelog | Version | Description | | ------- | ------------------------------------ | | 3.8.0 | Added | operationId: post-api-v1-rooms.export parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: rid: type: string description: The room ID. type: type: string description: |- How you want the room to be exported. The type of export selected determines the remaining required parameters. It can be either `email` or `file`. dateFrom: type: string description: |- Start date to begin fetching. Use `dateFrom` if the type is `file`. By default, it selects the oldest possible date. dateTo: type: string description: |- End date for fetching. By default it selects the current date. Use `dateTo` if the `type` is `file`. format: type: string description: |- The file type to export as. It can either be `html` or `json`. Use `format` if the `type` is `file`. toUsers: type: array items: type: string description: |- An array of users that should recieve the export. ecieve the export. It is required if `type` is `email`. toEmails: type: array items: type: string description: |- An array of any additional emails that should recieve the export. It is required if `type` is `email`. messages: type: array items: type: string description: |- An array of messageId for the messages that should be exported. It is required if `type` is `email`. subject: type: string description: |- The subject of the email. It is required if `type` is `email`. required: - rid - type examples: Example: value: rid: iu7jtPAhvEeAS5tNq type: file dateFrom: '2000-01-01' dateTo: '2021-11-25' format: html toUsers: - test.user toEmails: - test@test.com messages: - yd6NBgNoiWATgDoFt - BoCjicj9DdYoMHHeo - tajMB3aX3sawFWe8W subject: 'Test Subject ' responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Room ID: value: success: false error: '[error-invalid-room]' errorType: error-invalid-room Invalid Format: value: success: false error: '[error-invalid-format]' errorType: error-invalid-format Invalid Params: value: success: false error: '[error-invalid-params]' errorType: error-invalid-params '401': $ref: '#/components/responses/authorizationError' '403': $ref: '#/components/responses/forbiddenError' /api/v1/rooms.muteUser: post: tags: - Rooms summary: Mute User in Room description: | Mute a particular user in a room. Permission required: `mute-user`. The room becomes read-only for the muted user. They can still view messages but cannot send any until unmuted. ### Changelog | Version | Description | | ------- | ------------------------------------ | | 6.8.0 | Added | operationId: post-api-v1-rooms.muteUser parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - userId - roomId properties: userId: type: string example: CkCPNfjfhiwWLqC description: 'The user that you want to mute. Alternatively, use the `username` parameter and enter the username as the value.' roomId: type: string example: JZ8Y2dLfYhsg323Rf description: The room ID. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid User: value: success: false error: 'The required "userId" or "username" param provided does not match any users [error-invalid-user]' errorType: error-invalid-user Invalid Params: value: success: false error: |- must have required property 'userId' must have required property 'username' must match exactly one schema in oneOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.unmuteUser: post: tags: - Rooms summary: Unmute User in Room description: | Unmute a particular user in a room. Permission required: `mute-user` ### Changelog | Version | Description | | ------- | ------------------------------------ | | 6.8.0 | Added | operationId: post-api-v1-rooms.unmuteUser parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - userId - roomId properties: userId: type: string example: CkCPNfjfhiwWLqC description: 'The user that you want to unmute. Alternatively, use the `username` parameter.' roomId: type: string example: JZ8Y2dLfYhsg323Rf description: The room ID. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid User: value: success: false error: 'The required "userId" or "username" param provided does not match any users [error-invalid-user]' errorType: error-invalid-user Example 2: value: success: false error: |- must have required property 'userId' must have required property 'username' must match exactly one schema in oneOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.createDiscussion: post: tags: - Rooms summary: Create Discussion description: |- Creates a new discussion for the room. It requires at least one of the following permissions: `start-discussion` OR `start-discussion-other-user`, AND must be with the following setting enabled: `Discussion_enabled`. When **Force end-to-end encryption on private rooms** is enabled, you cannot create a discussion under an unencrypted private room. Make the parent room public or enable encryption on it before creating the discussion. ### Changelog | Version | Description | | ------- | --------------------------------------------------------------------------------------------- | | 8.8.0 | Added forced encryption checks for private-room discussions. | | 1.0.0 | Added | operationId: post-api-v1-rooms.createDiscussion parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: prid: type: string description: Parent room ID of the discussion. t_name: type: string description: Discussion name. users: type: array items: type: string description: 'Array of users to join in the discussion, if not provided, it will be an empty array. (Note: if provided, it must be an array).' pmid: type: string description: Parent message ID (if the discussion comes from a message). reply: type: string description: The reply of the discussion. required: - prid - t_name examples: Example: value: prid: GENERAL t_name: Discussion Name responses: '200': description: OK content: application/json: schema: type: object properties: discussion: type: object properties: rid: type: string name: type: string fname: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string topic: type: string prid: type: string ts: type: string ro: type: boolean sysMes: type: boolean default: type: boolean _updatedAt: type: string _id: type: string success: type: boolean examples: Success: value: discussion: rid: cgk88DHLHexwMaFWh name: WJNEAM7W45wRYitHo fname: Discussion Name t: p msgs: 0 usersCount: 0 u: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test topic: general prid: GENERAL ts: '2019-04-03T01:35:32.271Z' ro: false sysMes: true default: false _updatedAt: '2019-04-03T01:35:32.280Z' _id: cgk88DHLHexwMaFWh success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Private room encryption is enforced: value: success: false error: 'Workspace policy requires all private rooms to be encrypted. To create this discussion, make the parent channel public or enable encryption on it. [error-encrypted-private-rooms-enforced-discussion]' errorType: error-encrypted-private-rooms-enforced-discussion '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.images: get: tags: - Rooms summary: Get Room Images description: Retrieves the images of a room that you are a member of. operationId: get-api-v1-rooms.images parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: roomId in: query description: The room ID. schema: type: string example: 6630e42b72f069422b1022c1 example: 654c9d1ca2f73c7460e1918b required: true - schema: type: string example: 666fdecb4ac1a8e6404ededd in: query name: startingFromId description: Filter images using the file ID. allowEmptyValue: true - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' responses: '200': description: OK content: application/json: schema: type: object properties: files: type: array items: type: object properties: _id: type: string name: type: string size: type: integer type: type: string rid: type: string userId: type: string store: type: string _updatedAt: type: string identify: type: object properties: format: type: string size: type: object properties: width: type: integer height: type: integer complete: type: boolean etag: type: string path: type: string progress: type: integer token: type: string uploadedAt: type: string uploading: type: boolean url: type: string typeGroup: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: files: - _id: 666fdecb4ac1a8e6404ededd name: oauth-screen.png size: 78441 type: image/png rid: 6630e42b72f069422b1022c1 userId: yuT9xp9eEd6HqB3n8 store: 'GridFS:Uploads' _updatedAt: '2024-06-17T06:59:23.608Z' identify: format: png size: width: 1580 height: 884 complete: true etag: yvaG9cjz6YRRdMg4L path: '/ufs/GridFS:Uploads/666fdecb4ac1a8e6404ededd/oauth-screen.png' progress: 1 token: 1888eA0A0B uploadedAt: '2024-06-17T06:59:23.602Z' uploading: false url: 'https://pro.writing-demo.dev.rocket.chat/ufs/GridFS:Uploads/666fdecb4ac1a8e6404ededd/oauth-screen.png' typeGroup: image - _id: 666fddea4ac1a8e6404eded7 name: 11.jpg size: 83832 type: image/jpeg rid: 6630e42b72f069422b1022c1 userId: yuT9xp9eEd6HqB3n8 store: 'GridFS:Uploads' _updatedAt: '2024-06-17T06:55:38.044Z' identify: format: jpeg size: width: 839 height: 932 complete: true etag: 3jZf7SJZFCPpf9JK8 path: '/ufs/GridFS:Uploads/666fddea4ac1a8e6404eded7/11.jpg' progress: 1 token: 498bb849C8 uploadedAt: '2024-06-17T06:55:38.029Z' uploading: false url: 'https://pro.writing-demo.dev.rocket.chat/ufs/GridFS:Uploads/666fddea4ac1a8e6404eded7/11.jpg' typeGroup: image count: 50 offset: 0 total: 2 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Params: value: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/audit/rooms.members: parameters: [ ] get: summary: Audit and Get Room Members tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: members: type: array items: type: object properties: _id: type: string status: type: string name: type: string username: type: string _updatedAt: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Example 1: value: members: - _id: FSA63o85Poa2EQvAH status: offline name: cat kate username: cat.kate _updatedAt: '2024-08-27T09:07:03.795Z' count: 1 offset: 0 total: 1 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' '403': $ref: '#/components/responses/forbiddenError' operationId: get-api-v1-audit-rooms.members description: |-

Audit any public or private room and view the room members. You don't need to be a member of the room. Permission required: `view-members-list-all-rooms` ### Changelog | Version | Description | | ------- | ----------- | | 6.12.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: 66cd971f6fcbb8e8b3cf8e69 in: query name: roomId description: Enter the room ID that you want to audit. required: true - schema: type: string in: query name: filter description: Filter the results using the text that you want to view. - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' /api/v1/rooms.membersOrderedByRole: get: summary: Get Room Members Ordered by Role tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: members: type: array items: type: object properties: _id: type: string username: type: string status: type: string _updatedAt: type: string name: type: string roles: type: array items: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Example 1: value: members: - _id: C38WSSzrGd2NCjzqJ username: test.cat status: online _updatedAt: '2025-01-22T07:49:47.830Z' name: test.cat roles: - owner - _id: P2dgWPPw5veigwcdK status: offline _updatedAt: '2025-01-22T07:13:19.734Z' name: Fun Smith username: fun.smith roles: - moderator - _id: CNmyTxexxauJ4wrTW username: agent1 status: offline _updatedAt: '2025-01-22T07:32:57.238Z' name: agent1 - _id: FSA63o85Poa2EQvAH status: offline name: cat kate username: cat.kate _updatedAt: '2025-01-22T08:04:12.251Z' roles: - leader count: 4 offset: 0 total: 4 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: |- must have required property 'roomId' must have required property 'roomName' must match exactly one schema in oneOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-rooms.membersOrderedByRole description: |- Get room members ordered by their roles. This endpoint sorts the members according to their role in the room in the order `Owners` > `Moderators` > all other members. This can be reversed using the query paramter `sort={"rolePriority":-1}`. You need not be a member of the room. If the room is a broadcast room, you need the `view-broadcast-member-list` permission to view the room members. ### Changelog | Version | Description | | ------- | ----------- | | 7.3.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: 66cd971f6fcbb8e8b3cf8e69 in: query name: roomId description: Enter the room ID. required: true - schema: type: string example: test-team in: query name: roomName description: 'Instead of using the room ID, you can enter the room name.' - schema: type: string example: user in: query name: filter description: Filter the results by using the text that you want to view. - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - schema: type: string in: query name: sort description: |- Sort the rooms in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON string. The options are as follows: * `rolePriority`: Sort by priority of role (`Owners` > `Moderators` > all other members). For example, `sort={"rolePriority":-1}` * `username`: Sort by usernames. For example, `sort={"username":-1}` - schema: type: array items: type: string in: query name: status description: 'Enter the user status for which you want the results. For example, `online`, `away`, `offline`.' /api/v1/teams.create: post: tags: - Teams summary: Create a New Team description: |- Create a new public or private team in the workspace. Permission required: `create-team`. When you create a team from an existing room by passing `room.id`, you also need the `edit-room` permission for that room. ### Changelog | Version | Description | | ------- | ----------- | | 8.7.0 | Enforced room permission checks when creating a team from an existing room. | | 3.13.0 | Added | operationId: post-api-v1-teams.create parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: name: type: string description: The team name. type: type: integer description: 'Privacy of the team (0 - Public, 1 - Private).' members: type: array description: The user IDs to add to the team when it is created. items: type: string room: type: object properties: id: type: string description: The ID of an existing room to use as the team's main room. readOnly: type: boolean sidepanel: type: object description: List the team's channels or discussions to be displayed in the sidepanel. properties: items: type: array description: The options are `discussions` and `channels`. items: type: string example: '["discussions", "channels"]' owner: type: string description: Set the owner of the team. required: - name - type examples: Create a public team: value: name: teamName type: 0 members: - 8dugqGhuRvCBLdZft room: readOnly: true sidepanel: items: - discussions - channels Create a team from an existing room: value: name: teamName type: 0 room: id: 6513afeda2f73c7460e18c86 responses: '200': description: |- OK Note that the `roomId` is main room ID of the team. content: application/json: schema: type: object properties: team: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string success: type: boolean examples: Team created: value: team: _id: 651619e3a2f73c7460e18cc5 name: teamName type: 0 createdAt: '2023-09-29T00:27:15.189Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: roxie _updatedAt: '2023-09-29T00:27:15.189Z' roomId: 651619e3a2f73c7460e18cc7 success: true '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing room permissions: value: success: false error: unauthorized /api/v1/teams.listAll: get: tags: - Teams summary: Get List of All Teams description: |- Lists all the teams and their information. Permission required: `view-all-teams` operationId: get-api-v1-teams.listAll parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' responses: '200': description: |- OK Note that the `roomId` is main room ID of the team. content: application/json: schema: type: object properties: teams: type: array items: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string rooms: type: integer numberOfUsers: type: integer total: type: integer count: type: integer offset: type: integer success: type: boolean examples: Success: value: teams: - _id: 63f3efc4b000b6b6d86704b2 name: test-audit type: 0 createdAt: '2023-02-20T22:10:12.733Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: test.test _updatedAt: '2023-02-20T22:10:12.843Z' roomId: 6GFJ3tbmHiyHbahmC rooms: 0 numberOfUsers: 2 - _id: 6435624052492a08c3a756fd name: Test-team type: 0 createdAt: '2023-04-11T13:36:00.496Z' createdBy: _id: rYhzFRd2QZjNwAAXX username: rodriq _updatedAt: '2023-04-11T13:36:00.855Z' roomId: h5gPM3Wpip8nEFwbu rooms: 0 numberOfUsers: 2 - _id: 65149c7ea2f73c7460e18cab name: messages type: 0 createdAt: '2023-09-27T21:19:58.972Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: roxie _updatedAt: '2023-09-27T21:19:59.038Z' roomId: 6513afeda2f73c7460e18c86 rooms: 0 numberOfUsers: 2 total: 3 count: 3 offset: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.list: get: tags: - Teams summary: Get List of Teams description: Lists the public and private teams the request sender is part of. operationId: get-api-v1-teams.list parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/query' responses: '200': description: |- OK Note that the `roomId` is main room id of the team. content: application/json: schema: type: object properties: teams: type: array items: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string rooms: type: integer numberOfUsers: type: integer total: type: integer count: type: integer offset: type: integer success: type: boolean examples: Success: value: teams: - _id: 63f3efc4b000b6b6d86704b2 name: test-audit type: 0 createdAt: '2023-02-20T22:10:12.733Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: test.test _updatedAt: '2023-02-20T22:10:12.843Z' roomId: 6GFJ3tbmHiyHbahmC rooms: 0 numberOfUsers: 2 - _id: 65149c7ea2f73c7460e18cab name: messages type: 0 createdAt: '2023-09-27T21:19:58.972Z' createdBy: _id: rbAXPnMktTFbNpwtJ username: roxie _updatedAt: '2023-09-27T21:19:59.038Z' roomId: 6513afeda2f73c7460e18c86 rooms: 0 numberOfUsers: 2 total: 2 count: 2 offset: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.info: get: tags: - Teams summary: Get Team Info description: |- Gets a team's information. If the team is not public, the request sender must be a member of the team, or must have the `view-all-teams` permission. operationId: get-api-v1-teams.info parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-TeamId' - $ref: '#/components/parameters/Optional-TeamName' responses: '200': description: |- OK Note that the `roomId` is main room id of the team. content: application/json: schema: type: object properties: teamInfo: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string success: type: boolean examples: Success: value: teamInfo: _id: 607e0d9b49d493189836bfac name: Team1 type: 1 createdAt: '2021-04-19T23:09:15.106Z' createdBy: _id: FL2fZL4ERhwA3gWiS username: some.username _updatedAt: '2021-04-19T23:09:15.106Z' roomId: Dgh2xwJ3NFKWvKSqY success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.update: post: tags: - Teams summary: Update a Team description: |- Updates an existing team (name and type). Permission required: `edit-team` operationId: post-api-v1-teams.update parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamId: type: string description: The team ID. data: type: object description: 'The new team name and type (0 - public, 1 - private).' properties: name: type: string type: type: integer required: - teamId - data examples: Example: value: teamId: ByehQjC44FwMeiLbX data: name: newTeamName type: 1 responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.addMembers: post: tags: - Teams summary: Add Members to the Team description: |- Add members to a team. Permissions required: `add-team-member` or `edit-team-member` operationId: post-api-v1-teams.addMembers parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamId: type: string description: Enter the team ID. Alternatively, enter the `teamName` parameter and provide the team's name as the value. members: type: array description: The users (IDs and roles) to add to the team. items: type: object properties: userId: type: string roles: type: array items: type: string required: - teamId - members examples: Example: value: teamId: 63f3efc4b000b6b6d86704b2 members: - userId: rYhzFRd2QZjNwAAXX roles: - member responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.members: get: tags: - Teams summary: List Team Members description: |- List all members of a team. Permission required: `view-all-teams` operationId: get-api-v1-teams.members parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-TeamName' - $ref: '#/components/parameters/Optional-TeamId' - name: name in: query description: 'Search filter for the user''s name ' schema: type: string example: test - name: username in: query description: 'Search filter for the user''s username ' schema: type: string example: test.user - name: status in: query description: Search filter for the user's status schema: type: array items: type: string example: '["online", "away", "busy"]' responses: '200': description: OK content: application/json: schema: type: object properties: members: type: array items: type: object properties: user: type: object properties: _id: type: string username: type: string name: type: string status: type: string settings: type: object properties: preferences: type: object properties: themeAppearence: type: string profile: type: object roles: type: array items: type: string createdBy: type: object properties: _id: type: string username: type: string createdAt: type: string total: type: integer count: type: integer offset: type: integer success: type: boolean examples: Success: value: members: - user: _id: rbAXPnMktTFbNpwtJ username: roxie name: test test status: offline settings: preferences: themeAppearence: light profile: { } roles: - owner createdBy: _id: rbAXPnMktTFbNpwtJ username: test.test createdAt: '2023-02-20T22:10:12.740Z' - user: _id: 5fRTXMt7DMJbpPJfh username: test.test name: Testtest status: offline settings: profile: { } createdBy: _id: rbAXPnMktTFbNpwtJ username: test.test createdAt: '2023-07-11T00:23:01.346Z' total: 2 count: 2 offset: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.updateMember: post: tags: - Teams summary: Update Team Member Info description: |- Updates a team member's roles. Permission required: `edit-team-member` operationId: post-api-v1-teams.updateMembers parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - teamId - member properties: teamId: type: string description: 'Enter the team ID. Alternatively, enter the `teamName` parameter and provide the team''s name as the value.' member: type: object description: The users (IDs and roles) to add or update in the team. properties: userId: type: string description: Enter the user ID. roles: type: array items: {} examples: Example: value: teamId: 63f3efc4b000b6b6d86704b2 member: userId: rYhzFRd2QZjNwAAXX roles: - owner - leader responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.leave: post: tags: - Teams summary: Leave a Team description: Leave a team operationId: post-api-v1-teams.leave parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamId: type: string description: Enter the team ID. Alternatively, enter the `teamName` parameter and provide the team's name as the value. rooms: type: array description: The team room IDs to remove the user from. items: type: string required: - teamId - rooms examples: Example: value: teamName: team1 rooms: - 8dugqGhuRvCBLdZft responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.removeMember: post: tags: - Teams summary: Remove Member from Team description: |- Removes a member from a team. Permission required: `edit-team-member` operationId: post-api-v1-teams.removeMember parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: description: '' content: application/json: schema: type: object properties: teamId: type: string description: Enter the team ID. Alternatively, enter the `teamName` parameter and provide the team's name as the value. userId: type: string description: The user ID to remove from the team. rooms: type: array description: The rooms (IDs) from which the user should be removed. items: type: string required: - teamId - userId examples: Example: value: teamId: 63f3efc4b000b6b6d86704b2 userId: rYhzFRd2QZjNwAAXX rooms: - JKa7R9zu2DinBhBN9 responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.delete: post: tags: - Teams summary: Delete a Team description: |- Removes a team. Permission required: `delete-team` The deletion completes even if the team's main room no longer exists, for example after an interrupted deletion. In that case, the main room is skipped, the team is removed, and the team name becomes available again. You can retry an interrupted deletion with this endpoint. ### Changelog | Version | Description | | ------- | ----------- | | 8.9.0 | Succeeds when the main room is missing. | | 3.13.0 | Added | operationId: post-api-v1-teams.delete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamName: type: string description: Enter the team name. This parameter is required if `teamId` is not provided. teamId: type: string description: Enter the team ID. This parameter is required if `teamName` is not provided. roomsToRemove: type: array description: The room IDs to delete along with the team. items: type: string example: "8dugqGhuRvCBLdZft" examples: Example: value: teamId: mLGZGywfmLGZGywf roomsToRemove: - 8dugqGhuRvCBLdZft responses: '200': $ref: '#/components/responses/trueSuccess' '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.autocomplete: get: tags: - Teams summary: Autocomplete Team description: List the teams whose names match a given pattern. operationId: get-api-v1-teams.autocomplete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: name in: query description: The pattern (search filter for team names). required: true schema: type: string example: team responses: '200': description: OK content: application/json: schema: type: object properties: teams: type: array items: type: object properties: _id: type: string name: type: string fname: type: string t: type: string teamId: type: string success: type: boolean examples: Success: value: teams: - _id: Dgh2xwJ3NFKWvKSqY name: team1 fname: team1 t: p teamId: 607e0d9b49d493189836bfac success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.convertToChannel: post: tags: - Teams summary: Convert Team to Channel description: |- Convert a team to a channel. Permission required: `convert-team` operationId: post-api-v1-teams.convertToChannel parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamId: type: string description: The team ID that you want to convert to a channel. required: - teamId examples: Example: value: teamId: 612b8ae982d286c3d1f5db31 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Invalid Team Id: value: success: false error: team-does-not-exist Team Id or Team name is required: value: success: false error: missing-teamId-or-teamName '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.addRooms: post: tags: - Teams summary: Add Rooms to a Team description: |- Add existing rooms to a team. Permission required: `move-room-to-team` operationId: post-api-v1-teams.addRooms parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: teamId: type: string description: Enter the team ID to which you want to add the rooms. Alternatively, enter the `teamName` parameter and provide the team's name as the value. rooms: type: array description: The IDs of the rooms to be added to the team. items: type: string required: - teamId - rooms examples: Example: value: teamId: 607e0d9b49d493189836bfac rooms: - 8Z7eRsibvD5AANfmK responses: '200': description: OK content: application/json: schema: type: object properties: rooms: type: array items: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object teamId: type: string success: type: boolean examples: Success: value: rooms: - _id: JKa7R9zu2DinBhBN9 fname: Livestream customFields: { } description: '' broadcast: false encrypted: false federated: false name: Livestream t: c msgs: 15 usersCount: 3 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-02-22T17:15:26.989Z' ro: false default: false sysMes: true _updatedAt: '2023-09-26T01:05:39.641Z' lm: '2023-09-14T12:06:00.594Z' lastMessage: _id: rtf5JoPLQup3X7Aof t: videoconf msg: '' groupable: false blocks: - type: video_conf blockId: 6502f728a2f73c7460df6f71 callId: 6502f728a2f73c7460df6f71 appId: videoconf-core ts: '2023-09-14T12:06:00.594Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test rid: JKa7R9zu2DinBhBN9 _updatedAt: '2023-09-14T12:06:00.685Z' urls: [ ] mentions: [ ] channels: [ ] teamId: 63f3efc4b000b6b6d86704b2 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.removeRoom: post: tags: - Teams summary: Remove Room from the Team description: |- Removes a room from a team. Permissions required: `remove-team-channel`, `view-all-team-channels` operationId: post-api-v1-teams.removeRoom parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' requestBody: content: application/json: schema: type: object properties: teamName: type: string description: Enter the team name. This parameter is required if `teamId` is not provided. example: team01 teamId: type: string description: Enter the team ID. This parameter is required if `teamName` is not provided. example: d8eiFT9fIwfs roomId: type: string description: The room ID to be removed from the team. example: 8dugqGhuRvCBLdZft examples: Example: value: teamId: 63f3efc4b000b6b6d86704b2 roomId: JKa7R9zu2DinBhBN9 responses: '200': description: OK content: application/json: schema: type: object properties: room: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object success: type: boolean examples: Success: value: room: _id: JKa7R9zu2DinBhBN9 fname: Livestream customFields: { } description: '' broadcast: false encrypted: false federated: false name: Livestream t: c msgs: 15 usersCount: 3 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-02-22T17:15:26.989Z' ro: false default: false sysMes: true _updatedAt: '2023-09-29T05:51:47.779Z' lm: '2023-09-14T12:06:00.594Z' lastMessage: _id: rtf5JoPLQup3X7Aof t: videoconf msg: '' groupable: false blocks: - type: video_conf blockId: 6502f728a2f73c7460df6f71 callId: 6502f728a2f73c7460df6f71 appId: videoconf-core ts: '2023-09-14T12:06:00.594Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test rid: JKa7R9zu2DinBhBN9 _updatedAt: '2023-09-14T12:06:00.685Z' urls: [ ] mentions: [ ] channels: [ ] success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.updateRoom: post: tags: - Teams summary: Update Room in a Team description: |- Updates a room from a team. Permissions required: `edit-team-channel`, `view-all-team-channels` operationId: post-api-v1-teams.updateRoom parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The room ID that you want to update. isDefault: type: boolean description: Sets the room as auto-join (true) or not (false). required: - roomId - isDefault examples: Example: value: roomId: JKa7R9zu2DinBhBN9 isDefault: true responses: '200': description: OK content: application/json: schema: type: object properties: room: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object teamId: type: string teamDefault: type: boolean success: type: boolean examples: Success: value: room: _id: JKa7R9zu2DinBhBN9 fname: Livestream customFields: { } description: '' broadcast: false encrypted: false federated: false name: Livestream t: c msgs: 16 usersCount: 4 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-02-22T17:15:26.989Z' ro: false default: false sysMes: true _updatedAt: '2023-09-29T06:00:18.859Z' lm: '2023-09-14T12:06:00.594Z' lastMessage: _id: rtf5JoPLQup3X7Aof t: videoconf msg: '' groupable: false blocks: - type: video_conf blockId: 6502f728a2f73c7460df6f71 callId: 6502f728a2f73c7460df6f71 appId: videoconf-core ts: '2023-09-14T12:06:00.594Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test rid: JKa7R9zu2DinBhBN9 _updatedAt: '2023-09-14T12:06:00.685Z' urls: [ ] mentions: [ ] channels: [ ] teamId: 63f3efc4b000b6b6d86704b2 teamDefault: true success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.listRooms: get: tags: - Teams summary: List Rooms of a Team description: |- List all rooms in a team. Permissions required: `view-all-teams`, `view-all-team-channels` operationId: get-api-v1-teams.listRooms parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-TeamId' - $ref: '#/components/parameters/Optional-TeamName' - name: type in: query description: The room's type (search filter). schema: type: string example: autoJoin - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' responses: '200': description: OK content: application/json: schema: type: object properties: rooms: type: array items: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object teamId: type: string teamDefault: type: boolean total: type: integer count: type: integer offset: type: integer success: type: boolean examples: Success: value: rooms: - _id: JKa7R9zu2DinBhBN9 fname: Livestream customFields: { } description: '' broadcast: false encrypted: false federated: false name: Livestream t: c msgs: 16 usersCount: 4 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-02-22T17:15:26.989Z' ro: false default: false sysMes: true _updatedAt: '2023-09-29T06:02:30.250Z' lm: '2023-09-14T12:06:00.594Z' lastMessage: _id: rtf5JoPLQup3X7Aof t: videoconf msg: '' groupable: false blocks: - type: video_conf blockId: 6502f728a2f73c7460df6f71 callId: 6502f728a2f73c7460df6f71 appId: videoconf-core ts: '2023-09-14T12:06:00.594Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test rid: JKa7R9zu2DinBhBN9 _updatedAt: '2023-09-14T12:06:00.685Z' urls: [ ] mentions: [ ] channels: [ ] teamId: 63f3efc4b000b6b6d86704b2 teamDefault: true total: 1 count: 1 offset: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.listRoomsOfUser: get: tags: - Teams summary: List User Rooms of a Team description: |- Lists only the team's rooms that a particular user has joined. Permissions required: `view-all-teams`, `view-all-team-channels` operationId: get-api-v1-teams.listRoomsOfUser parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/Optional-TeamName' - $ref: '#/components/parameters/Optional-TeamId' - name: userId in: query description: The user ID. required: true schema: type: string example: rbAXrutTFbNprfn - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' responses: '200': description: OK content: application/json: schema: type: object properties: rooms: type: array items: type: object properties: _id: type: string fname: type: string customFields: type: object description: type: string broadcast: type: boolean encrypted: type: boolean federated: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string lm: type: string lastMessage: type: object properties: _id: type: string t: type: string msg: type: string groupable: type: boolean blocks: type: array items: type: object properties: type: type: string blockId: type: string callId: type: string appId: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string rid: type: string _updatedAt: type: string urls: type: array items: type: object mentions: type: array items: type: object channels: type: array items: type: object teamId: type: string teamDefault: type: boolean isLastOwner: type: boolean total: type: integer count: type: integer offset: type: integer success: type: boolean examples: Success: value: rooms: - _id: JKa7R9zu2DinBhBN9 fname: Livestream customFields: { } description: '' broadcast: false encrypted: false federated: false name: Livestream t: c msgs: 16 usersCount: 4 u: _id: rbAXPnMktTFbNpwtJ username: roxie ts: '2023-02-22T17:15:26.989Z' ro: false default: false sysMes: true _updatedAt: '2023-09-29T06:02:30.250Z' lm: '2023-09-14T12:06:00.594Z' lastMessage: _id: rtf5JoPLQup3X7Aof t: videoconf msg: '' groupable: false blocks: - type: video_conf blockId: 6502f728a2f73c7460df6f71 callId: 6502f728a2f73c7460df6f71 appId: videoconf-core ts: '2023-09-14T12:06:00.594Z' u: _id: rbAXPnMktTFbNpwtJ username: test.test name: test test rid: JKa7R9zu2DinBhBN9 _updatedAt: '2023-09-14T12:06:00.685Z' urls: [ ] mentions: [ ] channels: [ ] teamId: 63f3efc4b000b6b6d86704b2 teamDefault: true isLastOwner: true total: 1 count: 1 offset: 0 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/teams.listChildren: get: tags: - Teams summary: List Rooms and Discussions of a Team description: |- Lists a particular team's public rooms, discussions, and the rooms (public/private) a user is part of from the team's main room. Currently, this endpoint returns the discussions from the parent team rooms only; discussions from sub-channels are not returned. operationId: get-api-v1-teams.listChildren parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/Optional-TeamName' - $ref: '#/components/parameters/Optional-TeamId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - schema: type: string in: query name: filter description: Filter the results using the text you want to find. - schema: type: string in: query name: type description: 'You can choose the type of rooms you want in the response. Enter the value as `channels` or `discussions`. If you don''t enter any value, both types are returned.' - schema: type: string example: 66c82d78237405fc05fc1eef in: query name: roomId description: The room ID. This parameter is required if you have not provided the `teamId` or the `teamName`. responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer data: type: array items: type: object properties: _id: type: string fname: type: string _updatedAt: type: string topic: type: string broadcast: type: boolean encrypted: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string name: type: string ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean teamId: type: string teamMain: type: boolean lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object properties: { } mentions: type: array items: type: object properties: { } channels: type: array items: type: object properties: { } md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string customFields: type: object properties: { } offset: type: integer count: type: integer success: type: boolean examples: Success: value: total: 2 data: - _id: 66c82d78237405fc05fc1eef fname: test-team _updatedAt: '2024-09-20T12:27:38.725Z' topic: '' broadcast: false encrypted: false name: test-team t: c msgs: 3 usersCount: 1 u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat ts: '2024-08-23T06:34:32.413Z' ro: false default: false sysMes: true teamId: 66c82d78237405fc05fc1ef1 teamMain: true lastMessage: _id: ZaeoxcCsHLutRkh9m rid: 66c82d78237405fc05fc1eef msg: testing ts: '2024-09-20T12:27:38.634Z' u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat _updatedAt: '2024-09-20T12:27:38.686Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: testing lm: '2024-09-20T12:27:38.634Z' - _id: 66ed2dba40141d95f32c292b fname: new-channel _updatedAt: '2024-09-20T12:29:08.284Z' customFields: { } topic: '' broadcast: false encrypted: false name: new-channel t: p msgs: 3 usersCount: 2 u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat ts: '2024-09-20T08:09:30.417Z' ro: false teamId: 66c82d78237405fc05fc1ef1 default: false sysMes: true lastMessage: _id: xZhJfE4rmaosjHZCe rid: 66ed2dba40141d95f32c292b msg: testing ts: '2024-09-20T12:27:53.356Z' u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat _updatedAt: '2024-09-20T12:27:53.397Z' urls: [ ] mentions: [ ] channels: [ ] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: testing lm: '2024-09-20T12:27:53.356Z' offset: 0 count: 50 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: |- must have required property 'teamId' must have required property 'teamName' must have required property 'roomId' must match exactly one schema in oneOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.online: get: tags: - Groups summary: Get Group Online Users description: |- Lists all online users of a particular group (private channel). You will not be able to view the users if you are not a member of this private channel, unless you have admin permissions. ### Changelog | Version | Description | | ------- | ----------- | | 0.52.0 | Added | |7.0.0 | Replaced `query` parameter with `_id` parameter | operationId: get-api-v1-groups.online parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: _id in: query description: |- Enter the group's ID. You can find list of groups IDs using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. required: true schema: type: string example: "5HmCfpoB7jp2uibTC" responses: '200': description: OK content: application/json: schema: type: object properties: online: type: array items: type: object properties: _id: type: string username: type: string success: type: boolean examples: Success: value: online: - _id: 47cRd58HnWwpqxhaZ username: test - _id: BsxzC22xQ43taWdff username: uniqueusername success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Error if you are not a member of the private channel: value: success: false error: 'Not Allowed [error-not-allowed]' errorType: error-not-allowed Invalid or missing query parameter: value: success: false error: Invalid query '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.getIntegrations: get: tags: - Groups summary: Get Group Integrations description: |- Retrieves the integrations that the group/channel has. At least one of the following integration permissions is required: * `manage-incoming-integrations` * `manage-own-incoming-integrations` * `manage-outgoing-integrations` * `manage-own-outgoing-integrations` It will return the integrations based on the user's permission. ### Changelog | Version | Description | | ------- | ----------- | | 1.1.0 | Separate permissions in incoming and outgoing. | | 0.49.0 | Added | operationId: get-api-v1-groups.getIntegrations parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: 6731de043b74d3c57d334d0c in: query name: roomId description: |- Enter the private channel's ID. Alternatively, you can enter the room name using the `roomName` query parameter. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. required: true - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' responses: '200': description: OK content: application/json: schema: type: object properties: integrations: type: array items: type: object properties: _id: type: string enabled: type: boolean username: type: string alias: type: string avatar: type: string name: type: string triggerWords: type: array items: type: string urls: type: array items: type: string token: type: string script: type: string scriptEnabled: type: boolean impersonateUser: type: boolean scriptCompiled: type: string scriptError: type: string type: type: string userId: type: string channel: type: array items: type: string _createdAt: type: string _createdBy: type: object properties: username: type: string _id: type: string _updatedAt: type: string success: type: boolean examples: Success: value: integrations: - _id: WMQDChpnYTRmFre9h enabled: true username: rocket.cat alias: Guggy avatar: 'http://res.guggy.com/logo_128.png' name: Guggy triggerWords: - '!guggy' - guggy - gif+ urls: - 'http://text2gif.guggy.com/guggify' token: 8DFS89DMKLWEN script: |- const config = { color: '#ffffff' }; class Script { prepare_outgoing_request({ request }) { const trigger = request.data.trigger_word + ' '; const phrase = request.data.text.replace(trigger, ''); request.headers['Content-Type']='application/json'; request.headers['apiKey']=request.data.token; return { url: request.url, headers: request.headers, data: {format: 'gif', sentence: phrase}, method: 'POST' }; } process_outgoing_response({ request, response }) { if(response.content.gif) { return { content: { attachments: [ { image_url: response.content.gif, color: ((config['color'] != '') ? '#' + config['color'].replace('#', '') : '#ffffff') } ] } }; } else { return { content: { text: 'Sorry I don\'t have a photo for you :disappointed_relieved:' } }; } } } scriptEnabled: true impersonateUser: false scriptCompiled: 'function _classCallCheck(instance,Constructor){if(!(instance instanceof Constructor)){throw new TypeError(''Cannot call a class as a function'')}}var config={color:''#ffffff''};var Script=function(){function Script(){_classCallCheck(this,Script)}Script.prototype.prepare_outgoing_request=function prepare_outgoing_request(_ref){var request=_ref.request;var trigger=request.data.trigger_word+'' '';var phrase=request.data.text.replace(trigger,'''');request.headers[''Content-Type'']=''application/json'';request.headers[''apiKey'']=request.data.token;return{url:request.url,headers:request.headers,data:{format:''gif'',sentence:phrase},method:''POST''}};Script.prototype.process_outgoing_response=function process_outgoing_response(_ref2){var request=_ref2.request;var response=_ref2.response;if(response.content.gif){return{content:{attachments:[{image_url:response.content.gif,color:config[''color'']!=''''?''#''+config[''color''].replace(''#'',''''):''#ffffff''}]}}}else{return{content:{text:''Sorry I don\''t have a photo for you :disappointed_relieved:''}}}};return Script}();' scriptError: "" type: webhook-outgoing userId: rocket.cat channel: - '#private-group-name' _createdAt: '2017-01-05T17:06:05.660Z' _createdBy: username: graywolf336 _id: R4jgcQaQhvvK6K3iY _updatedAt: '2017-01-05T17:06:05.660Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided Example 2: value: success: false error: 'User does not have the permissions required for this action [error-unauthorized]' '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.addAll: post: tags: - Groups summary: Add All Users to Group description: |- Add all workspace users to the private channel. You can do this if you are a member of the private channel or have admin permissions. ### Changelog | Version | Description | | ------- | ----------- | | 0.55.0 | Added | operationId: post-api-v1-groups.addAll parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- Enter the group ID. Alternatively, you can enter the name using the `roomName` query parameter. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. activeUsersOnly: type: boolean description: Add only active users to the room. required: - roomId examples: Example: value: roomId: ByehQjC44FwMeiLbX activeUsersOnly: 'true' responses: '200': description: OK content: application/json: schema: type: object properties: channel: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string success: type: boolean examples: Success: value: channel: _id: ByehQjC44FwMeiLbX name: groupname t: p usernames: - example - rocket.cat msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: example ts: '2016-05-30T13:42:25.304Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.addLeader: post: tags: - Groups summary: Add Group Leader description: |- Assign the `leader` role to a user in a private channel. Learn more about roles from the Roles in Rocket.Chat document. Permission required: `set-leader` ### Changelog | Version | Description | | ------- | ----------- | | 0.58.0 | Added. | operationId: post-api-v1-groups.addLeader parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The groups's (private channel) ID. example: ByehQjC44FwMeiLbX userId: type: string description: The user's ID. example: oCHkav5Zf6vmpu2W2 required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User is already a leader: value: success: false error: 'User is already a leader [error-user-already-leader]' errorType: error-user-already-leader '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.addModerator: post: tags: - Groups summary: Add Group Moderator description: |- Assign the `moderator` role to a user in a private channel. Learn more about roles from the Roles in Rocket.Chat document. Permission required: `set-moderator` ### Changelog | Version | Description | | ------- | ----------- | | 0.49.4 | Added. | operationId: post-api-v1-groups.addModerator parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The groups's (private channel) ID. example: ByehQjC44FwMeiLbX userId: type: string description: The user's ID. example: nSYqWzZ4GsKTX4dyK required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: nSYqWzZ4GsKTX4dyK responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.addOwner: post: tags: - Groups summary: Add Group Owner description: |- Assign `owner` role for a user in the current private channel. Learn more about roles from the Roles in Rocket.Chat document. ### Changelog | Version | Description | | ------- | ----------- | | 0.49.4 | Added. | operationId: post-api-v1-groups.addOwner parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: Enter the group's (private channel) ID. example: ByehQjC44FwMeiLbX userId: type: string description: Enter the user's ID. example: nSYqWzZ4GsKTX4dyK required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: nSYqWzZ4GsKTX4dyK responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.archive: post: tags: - Groups summary: Archive a Group description: |- Archive a private channel. You need the `archive-room` permission. ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.archive parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: |- The group ID that you want to archive. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. required: - roomId responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: No permission: value: success: false error: 'Not authorized [error-not-authorized]' errorType: error-not-authorized details: method: archiveRoom '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.close: post: tags: - Groups summary: Close Group description: |- Hides the private channel from the list of channels in the workspace sidebar, only if you're part of the group. It will reappear when someone sends a new message. You can search for hidden channels using the workspace **Directory**. ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.close parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: description: '' content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: |- The group ID that you want to close. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.counters: get: tags: - Groups summary: Get Group Counters description: |- Get the private channel information for the authenticated user. Permission required: `view-room-administration` ### Changelog | Version | Description | | ------- | ----------- | | 0.65.0 | Added | operationId: get-api-v1-groups.counters parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - name: userId in: query description: Counters for provided user ID (you need to have the `view-room-administration` permission for calling user). This parameter is optional schema: type: string responses: '200': description: |- OK **Note** The response returns the following information: - joined - Boolean flag that shows the particular user has joined the room or not. - members - Count of current room members. - unreads - Count of unread messages for specified user (calling user or for the provided `userId`). - unreadsFrom - Start date-time of unread interval for specified user. - msgs - Count of messages in the room. - latest - End date-time of unread interval for specified user (or date-time of last posted message). - userMentions - Count of user mentions in messages. content: application/json: schema: type: object properties: joined: type: boolean members: type: integer unreads: type: integer unreadsFrom: type: string msgs: type: integer latest: type: string userMentions: type: integer success: type: boolean examples: Success: value: joined: true members: 1 unreads: 1 unreadsFrom: '2018-02-18T21:51:20.091Z' msgs: 1 latest: '2018-02-23T17:20:17.345Z' userMentions: 0 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.create: post: tags: - Groups summary: Create Group description: |- Create a new private channel, optionally including specified users. Refer to the Channels documents for information on the available room options. The following permissions are required: * `create-p`: This permission is required to create a private channel. * `create-team-group`: This permission is required if you want to create a private channel from an existing team. ### Changelog | Version | Description | | ------- | ------------------------------------------------------------------------------------------- | | 8.8.0 | Added support for enforcing end-to-end encryption when creating private rooms. | | 6.4.1 | Added `excludeSelf` param | | 0.35.0 | Added | operationId: post-api-v1-groups.create parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the new private group. example: groupname readOnly: type: boolean description: Set if the private channel is read-only or not. The default value is false. example: false members: type: array description: The users to add to the private channel when it is created. items: type: string example: rocket.cat excludeSelf: type: boolean description: If set to true, the user calling the endpoint is not added as a member of the private channel. The default value is false. example: false customFields: type: object description: |- You add custom fields for private rooms using this parameter. Enter the key and value that you want to associate with this room. For example, `{ "company": "sell-and-more" }`. The custom fields are not displayed in the workspace UI. extraData: type: object description: |- Enter the following details for the object: Note: For more information, see Channels. properties: broadcast: type: boolean description: Whether the group should be a broadcast group. False by default. encrypted: type: boolean description: Whether the private room should use end-to-end encryption. When **Force end-to-end encryption on private rooms** is enabled, omit this field or set it to `true`. Setting it to `false` returns the `error-encrypted-private-rooms-enforced` error. Federated private rooms are exempt from this policy. teamId: type: string description: Enter the team ID for which you want to create a group. You will get an error if the team does not exist. required: - name examples: Example: value: name: groupname members: - rocket.cat readOnly: true excludeSelf: true customFields: type: default extraData: broadcast: true encrypted: true teamId: 658441562dd9f928ad9951aa responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: NtR6RQ7NvzA9ejecX name: testing t: p msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: tester ts: '2016-12-09T16:53:06.761Z' ro: false sysMes: true _updatedAt: '2016-12-09T16:53:06.761Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Name is required: value: success: false error: Body param "name" is required Private room encryption is enforced: value: success: false error: 'Workspace policy requires all private rooms to be encrypted. [error-encrypted-private-rooms-enforced]' errorType: error-encrypted-private-rooms-enforced '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.delete: post: tags: - Groups summary: Delete Group description: |- Delete a private room. The following permissions are required: * `delete-p`: To delete a private channel. * `delete-team-group`: To delete a private channel that is part of a team. ### Changelog | Version | Description | | ------- | ------------------------ | | 0.71.0 | Removed `group` property | | 0.49.0 | Added | operationId: post-api-v1-groups.delete parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: |- Enter the room ID. This parameter is required if no `roomName` is provided. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. roomName: type: string example: private-abc description: Enter the room name. This parameter is required if no `roomId` is provided. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: No permission: value: success: false error: 'Not allowed [error-not-allowed]' errorType: error-not-allowed details: method: eraseRoom '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.history: get: tags: - Groups summary: Get Group History description: |- Retrieves the messages from a private channel you belong to. ### Changelog | Version | Description | | ------- | ----------------------- | | 0.75.0 | Added `offset` property | | 0.48.0 | Added | operationId: get-api-v1-groups.history parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/RoomId' - name: latest in: query description: The end of the time range of messages to retrieve. The default value is the current date and time. schema: type: string example: '2025-09-30T13:42:25.304Z' - name: oldest in: query description: The start of the time range to retrieve messages. schema: type: string example: '2025-05-30T13:42:25.304Z' - name: inclusive in: query description: Whether messages sent on the latest and oldest dates should be included. The default value is false. schema: type: boolean example: true - name: unreads in: query description: Whether unread messages should be included in the response. The default value is false. schema: type: boolean example: false - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' responses: '200': description: OK content: application/json: schema: type: object properties: messages: type: array items: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string _updatedAt: type: string t: type: string groupable: type: boolean success: type: boolean examples: Success: value: messages: - _id: AkzpHAvZpdnuchw2a rid: ByehQjC44FwMeiLbX msg: hi ts: '2025-12-09T12:50:51.555Z' u: _id: y65tAmHs93aDChMWu username: testing _updatedAt: '2025-12-09T12:50:51.562Z' - _id: vkLMxcctR4MuTxreF t: uj rid: ByehQjC44FwMeiLbX ts: '2025-12-08T15:41:37.730Z' msg: testing2 u: _id: bRtgdhzM6PD9F8pSx username: testing2 groupable: false _updatedAt: '2025-12-08T16:03:25.235Z' - _id: bfRW658nEyEBg75rc t: uj rid: ByehQjC44FwMeiLbX ts: '2025-12-07T15:47:49.099Z' msg: testing u: _id: nSYqWzZ4GsKTX4dyK username: testing1 groupable: false _updatedAt: '2025-12-07T15:47:49.099Z' - _id: pbuFiGadhRZTKouhB t: uj rid: ByehQjC44FwMeiLbX ts: '2025-12-06T17:57:38.635Z' msg: testing u: _id: y65tAmHs93aDChMWu username: testing groupable: false _updatedAt: '2025-12-06T17:57:38.635Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.info: get: tags: - Groups summary: Get Group Information description: |- Retrieves the information about a private channel you belong to. ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: get-api-v1-groups.info parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string fname: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string customFields: type: object broadcast: type: boolean encrypted: type: boolean ts: type: string ro: type: boolean default: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMeiLbX name: testing fname: testing t: p msgs: 0 usersCount: 2 u: _id: HKKPmF8rZh45GMHWH username: marc.anp customFields: { } broadcast: false encrypted: false ts: '2020-05-21T13:16:24.749Z' ro: false default: false sysMes: true _updatedAt: '2020-05-21T13:16:24.772Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.invite: post: tags: - Groups summary: Invite Users to Group description: |- Invite one user or bulk users to a private channel. Any of the following permissions are required: * `add-user-to-joined-room`: This permission is required if you want to add users to the channel that you have joined. * `add-user-to-any-p-room`: This permission is required to add users to any private channel. You can identify the group by `roomId` or `roomName`, and the user(s) by `userId`, `username`, `userIds`, or `usernames`. ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.invite parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The group ID. This parameter is required if no `roomName` is provided. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX roomName: type: string description: The group name. This parameter is required if no `roomId` is provided. example: private-abc userId: type: string description: The ID of the user to be invited. This parameter is required if no `username`, `userIds`, or `usernames` is provided. example: nSYqWzZ4GsKTX4dyK username: type: string description: The username of the user to be invited. This parameter is required if no `userId`, `userIds`, or `usernames` is provided. example: john.doe userIds: type: array description: An array of user IDs to invite. This parameter is required if no `userId`, `username`, or `usernames` is provided. items: type: string example: - nSYqWzZ4GsKTX4dyK - SYqWzZ4Gsasdfgh usernames: type: array description: An array of usernames to invite. This parameter is required if no `userId`, `username`, or `userIds` is provided. items: type: string example: - john.doe - jane.doe examples: Invite by IDs: value: roomId: ByehQjC44FwMeiLbX userId: nSYqWzZ4GsKTX4dyK Invite by names: value: roomName: private-abc username: john.doe Invite multiple users by ID: value: roomId: ByehQjC44FwMeiLbX userIds: - nSYqWzZ4GsKTX4dyK - SYqWzZ4Gsasdfgh Invite multiple users by username: value: roomName: private-abc usernames: - john.doe - jane.doe responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string ts: type: string t: type: string name: type: string usernames: type: array items: type: string u: type: object properties: _id: type: string username: type: string msgs: type: integer _updatedAt: type: string lm: type: string success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMeiLbX ts: '2016-11-30T21:23:04.737Z' t: p name: testing usernames: - testing - testing1 u: _id: aobEdbYhXfu5hkeqG username: testing1 msgs: 1 _updatedAt: '2016-12-09T12:50:51.575Z' lm: '2016-12-09T12:50:51.555Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: Room parameter required: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided User parameter required: value: success: false error: 'Please provide "userId" or "username" or "userIds" or "usernames" as param [error-users-params-not-provided]' errorType: error-users-params-not-provided Permission required: value: success: false error: Not allowed [error-not-allowed] errorType: error-not-allowed details: method: addUsersToRoom '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.kick: post: tags: - Groups summary: Remove User from Group description: |- Remove a user from the private group/channel. Permission required: `kick-user-from-any-p-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.kick parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: Enter the private room ID from which you want to remove the user. example: ByehQjC44FwMeiLbX userId: type: string description: Enter the user ID that you want to remove. example: nSYqWzZ4GsKTX4dyK required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: nSYqWzZ4GsKTX4dyK responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMeiLbX name: invite-me t: p usernames: - testing1 msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' success: true '401': $ref: '#/components/responses/authorizationError' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: No permission: value: success: false error: 'Not allowed [error-not-allowed]' errorType: error-not-allowed details: method: removeUserFromRoom /api/v1/groups.leave: post: tags: - Groups summary: Leave Group description: |- Leave a private channel. Leave a private channel. If a group owner is leaving, they must set another owner before leaving the group. Permission required: `leave-p` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-groups.leave parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The group ID that you want to leave. responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMeiLbX name: invite-me t: p usernames: - testing2 msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: Example 1: value: success: false error: 'You are the last owner. Please set new owner before leaving the room. [error-you-are-last-owner]' errorType: error-you-are-last-owner details: method: leaveRoom Example 2: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.listAll: get: tags: - Groups summary: Get List of User Groups description: |- Lists all the private groups/channels of the workspace. Permission required: `view-room-administration` ### Changelog | Version | Description | | ------- | ------------------------------ | | 0.62.0 | Add 'query' parameter support. | | 0.59.0 | Added | operationId: get-api-v1-groups.listAll parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' responses: '200': description: OK content: application/json: schema: type: object properties: groups: type: array items: type: object properties: _id: type: string name: type: string fname: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string customFields: type: object properties: companyId: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string offset: type: integer count: type: integer total: type: integer success: type: boolean examples: Success: value: groups: - _id: xA52DRDM7dqx2PfTp name: private1 fname: private1 t: p msgs: 0 u: _id: 3WpJQkDHhrWPBvXuW username: admin customFields: companyId: org1 ts: '2018-01-21T21:05:06.729Z' ro: false sysMes: true _updatedAt: '2018-01-21T21:05:06.729Z' offset: 0 count: 1 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.list: get: tags: - Groups summary: Get Groups description: |- Lists all the private channels you are a member of. ### Changelog | Version | Description | | ------- | -------------------------------------------- | | 0.67.0 | Removed `query` parameter support. | | 0.62.0 | Add `query` parameter support. | | 0.49.0 | Count and offset query parameters supported. | | 0.33.0 | Added | operationId: get-api-v1-groups.list parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - schema: type: string in: query name: sort description: |- Sort the channels in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON object. The options are as follows: * `name`: Sort by the channel name. For example, `sort={"name":1}` (this is the default sorting mechanism). * `ts`: Sort by channel creation timestamp. For example, `sort={"ts":-1}` * `usersCount`: Sort by the number of users in the channel. For example, `sort={"usersCount":1}` responses: '200': description: OK content: application/json: schema: type: object properties: groups: type: array items: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string offset: type: integer count: type: integer total: type: integer success: type: boolean examples: Success: value: groups: - _id: ByehQjC44FwMeiLbX name: test-test t: p msgs: 0 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' - _id: t7qapfhZjANMRAi5w name: testing t: p msgs: 0 u: _id: y65tAmHs93aDChMWu username: testing2 ts: '2016-12-01T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:22:40.656Z' offset: 0 count: 1 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.members: get: tags: - Groups summary: List Group Members description: |- Lists the members of a private group. Permission required if the room is broadcast.: `view-broadcast-member-list` ### Changelog | Version | Description | | ------- | ----------- | | 0.59.0 | Added | operationId: get-api-v1-groups.members parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - name: status in: query description: The user's status (search filter). schema: type: array items: type: string example: '["online", "away"]' - name: filter in: query description: Extra search filters to be applied to the fields defined in the `Accounts_SearchFields` setting. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: members: type: array items: type: object properties: _id: type: string status: type: string name: type: string utcOffset: type: integer username: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: members: - _id: Q4GkX6RMepGDdQ7YJ status: online name: Marc Pow utcOffset: -3 username: marc.pow - _id: rocket.cat name: Rocket.Cat username: rocket.cat status: online utcOffset: 0 count: 2 offset: 0 total: 2 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.messages: get: tags: - Groups summary: Get Group Messages description: |- Lists all the messages in a private channel. ### Changelog | Version | Description | | ------- | ----------- | | 7.0.0 | Added `mentionIds`, `starredIds`, `pinned` query parameters.| | 0.59.0 | Added | operationId: get-api-v1-groups.messages parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - name: mentionIds in: query description: Filter the messages where a user has been mentioned by the userId. For a set of userIds, use an array (`["838ndhd79w", "dud0wu900"]`). schema: type: string example: 'dud0wu900' - name: starredIds in: query description: Filter the messages a user have starred by userId. For a set of userIds, use an array (`["838ndhd79w", "dud0wu900"]`). schema: type: string example: 'dud0wu900' - name: pinned in: query description: Filter pinned messages. schema: type: boolean example: 'true' responses: '200': description: OK content: application/json: schema: type: object properties: messages: type: array items: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string reactions: type: object properties: ':frowning2:': type: object properties: usernames: type: array items: type: string mentions: type: array items: type: object channels: type: array items: type: object starred: type: object properties: _id: type: string t: type: string groupable: type: boolean attachments: type: array items: $ref: '#/components/schemas/Attachment' count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: messages: - _id: CeXwh5eBbdrtvnqG6 rid: agh2Sucgb54RQ8dDo msg: s ts: '2018-10-05T13:48:21.616Z' u: _id: KPkEYwKKBKZnEEPpt username: marc.pow name: Marc Pow _updatedAt: '2018-10-05T13:48:49.535Z' reactions: ':frowning2:': usernames: - marcos.defendi mentions: [ ] channels: [ ] starred: _id: KPkEYwKKBKZnEEPpt - _id: MrAeupRiF9TvhMesK t: room_changed_privacy rid: agh2Sucgb54RQ8dDo ts: '2018-10-05T00:11:16.998Z' msg: Private Group u: _id: rocketchat.internal.admin.test username: rocketchat.internal.admin.test groupable: false _updatedAt: '2018-10-05T00:11:16.998Z' count: 2 offset: 0 total: 2 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: |- must have required property 'roomId' must have required property 'roomName' must match exactly one schema in oneOf [invalid-params] errorType: error-invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.moderators: get: tags: - Groups summary: Get Group Moderators description: |- Lists the moderators of a private channel. ### Changelog | Version | Description | | ------- | ----------- | | 0.70.0 | Added | operationId: get-api-v1-groups.moderators parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/Optional-RoomName' responses: '200': description: OK content: application/json: schema: type: object properties: moderators: type: array items: type: object success: type: boolean examples: Success: value: moderators: - _id: hifeRG56fjlsp username: marc.cat name: Marc Cat success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.open: post: tags: - Groups summary: Add Group to List description: |- Use this endpoint to add the private group/channel back to the list of rooms in the workspace sidebar, if you have used the groups.close endpoint to remove the channel from the sidebar. ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.open parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The room ID that you want to add to the sidebar. Alternatively, you can use the `roomName` parameter and enter the room name, instead of the ID. required: - roomId responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.removeLeader: post: tags: - Groups summary: Remove Group Leader description: |- Remove the `leader` role from a user in a private channel. Permission required: `set-leader` ### Changelog | Version | Description | | ------- | ----------- | | 0.58.0 | Added | operationId: post-api-v1-groups.removeLeader parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX userId: type: string description: The user ID. example: oCHkav5Zf6vmpu2W2 required: - roomId - userId examples: Example: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User is not a leader: value: success: false error: 'User is not a leader [error-user-not-leader]' errorType: error-user-not-leader '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.removeModerator: post: tags: - Groups summary: Remove Group Moderator description: |- Remove the `moderator` role from a user in a private channel. Permission required: `set-moderator` ### Changelog | Version | Description | | ------- | ----------- | | 0.49.4 | Added | operationId: post-api-v1-groups.removeModerator parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX userId: type: string description: The ID of the user to be removed from moderator role. Alternatively, you can use the `userName` parameter and enter the username, instead of the ID. example: oCHkav5Zf6vmpu2W2 required: - roomId - userId examples: Success: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided Example 2: value: success: false error: 'The required "userId" or "username" param was not provided [error-user-param-not-provided]' errorType: error-user-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.removeOwner: post: tags: - Groups summary: Remove Group Owner description: | Remove the `owner` role from a user in a private channel. Permission required: `set-owner` ### Changelog | Version | Description | | ------- | ----------- | | 0.49.4 | Added | operationId: post-api-v1-groups.removeOwner parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX userId: type: string description: 'The ID of the user to be removed as owner ' example: oCHkav5Zf6vmpu2W2 required: - roomId - userId examples: Success: value: roomId: ByehQjC44FwMeiLbX userId: oCHkav5Zf6vmpu2W2 responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided Example 2: value: success: false error: 'The required "userId" or "username" param was not provided [error-user-param-not-provided]' errorType: error-user-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.rename: post: tags: - Groups summary: Rename Group description: |- Rename a private channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.rename parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group's ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX name: type: string description: The new name of the private group. It can not be the same as another or the existing name. example: newname required: - roomId - name examples: Example: value: roomId: ByehQjC44FwMeiLbX name: new-name responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string usernames: type: array items: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMeiLbX name: new-name t: p usernames: - testing1 msgs: 4 u: _id: aobEdbYhXfu5hkeqG username: testing1 ts: '2016-12-09T15:08:58.042Z' ro: false sysMes: true _updatedAt: '2016-12-09T15:57:44.686Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The bodyParam "name" is required Example 2: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setAnnouncement: post: tags: - Groups summary: Set Group Announcement description: |- Set the private channel announcement. Announcements are displayed at the top of the rooms, under the header. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.70.0 | Added | operationId: post-api-v1-groups.setAnnouncement parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX announcement: type: string description: The announcement to set for the private group. example: Test announcement required: - roomId - announcement examples: Example: value: roomId: ByehQjC44FwMeiLbX announcement: Test announcement responses: '200': description: OK content: application/json: schema: type: object properties: announcement: type: string success: type: boolean examples: Success: value: announcement: Test out everything. success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setCustomFields: post: tags: - Groups summary: Set Group Custom Fields description: |- Set custom fields for the private channel. These custom fields are not displayed on the workspace UI. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.62.0 | Added | operationId: post-api-v1-groups.setCustomFields parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group's ID. Alternatively, use the `roomName` parameter and provide the room's name as the value. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: euzoT67Gx6nXcn66M customFields: type: object description: The custom fields to set for the private group. required: - roomId - customFields examples: Example: value: roomId: euzoT67Gx6nXcn66M customFields: company: sell-and-more responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string fname: type: string _updatedAt: type: string name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string name: type: string ts: type: string ro: type: boolean sidepanel: type: object properties: items: type: array items: type: string teamId: type: string teamMain: type: boolean rolePrioritiesCreated: type: integer lastMessage: type: object properties: _id: type: string rid: type: string msg: type: string ts: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object properties: {} mentions: type: array items: type: object properties: {} channels: type: array items: type: object properties: {} md: type: array items: type: object properties: type: type: string value: type: array items: type: object properties: type: type: string value: type: string lm: type: string encrypted: type: boolean e2eKeyId: type: string retention: type: object properties: enabled: type: boolean overrideGlobal: type: boolean announcement: type: string announcementDetails: type: string customFields: type: object properties: company: type: string success: type: boolean examples: Success: value: group: _id: 66c88dae237405fc05fc1f06 fname: api-team2 _updatedAt: '2025-11-20T08:26:12.813Z' name: api-team2 t: p msgs: 17 usersCount: 2 u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test.cat ts: '2024-08-23T13:25:02.959Z' ro: false sidepanel: items: - discussions teamId: 66c88daf237405fc05fc1f08 teamMain: true rolePrioritiesCreated: 2 lastMessage: _id: 3yXev48EfPnBwfvDN rid: 66c88dae237405fc05fc1f06 msg: hello world ts: '2025-10-28T06:32:52.861Z' u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: Test Cat _updatedAt: '2025-10-28T06:32:52.983Z' urls: [] mentions: [] channels: [] md: - type: PARAGRAPH value: - type: PLAIN_TEXT value: hello world lm: '2025-10-28T06:32:52.861Z' encrypted: false e2eKeyId: 8ee4c64e1012 retention: enabled: false overrideGlobal: false announcement: testing announcement announcementDetails: null customFields: company: sell-and-more success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The bodyParam "customFields" is required with a type like object. Example 2: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setDescription: post: tags: - Groups summary: Set Group Description description: |- Set the description for the private channel. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.setDescription parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX description: type: string description: Enter a description for the private channel. example: Test description required: - roomId - description examples: Example: value: roomId: ByehQjC44FwMeiLbX description: Test out everything responses: '200': description: OK content: application/json: schema: type: object properties: description: type: string success: type: boolean examples: Success: value: description: Testing out everything. success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The bodyParam "description" is required Example 2: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setPurpose: post: tags: - Groups summary: Set Group Purpose description: |- (Obsolete) Sets the description for the group/channel (the same as `groups.setDescription`). ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.setPurpose parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The private group ID. purpose: type: string description: The group purpose required: - roomId - purpose examples: Example: value: roomId: ByehQjC44FwMeiLbX purpose: Test out everything responses: '200': description: OK content: application/json: schema: type: object properties: purpose: type: string success: type: boolean examples: Success: value: purpose: Testing out everything. success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setReadOnly: post: tags: - Groups summary: Set Group as Read Only description: |- Set or unset a private channel as read-only. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.49.0 | Added | operationId: post-api-v1-groups.setReadOnly parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The private group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMei5LbX readOnly: type: boolean description: Boolean to represent the group read-only status example: true required: - roomId - readOnly examples: Example: value: roomId: ByehQjC44FwMei5LbX readOnly: true responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string usernames: type: array items: type: string joinCodeRequired: type: boolean muted: type: array items: type: object success: type: boolean examples: Success: value: group: _id: ByehQjC44FwMei5LbX name: testing-private t: p msgs: 0 u: _id: aiPqNoGkjpNDiRx6d username: goose160 ts: '2017-01-05T18:02:50.754Z' ro: true sysMes: true _updatedAt: '2017-01-05T19:02:24.429Z' usernames: - goose160 - graywolf336 joinCodeRequired: true muted: [ ] success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided Example 2: value: success: false error: The bodyParam "readOnly" is required '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setTopic: post: tags: - Groups summary: Set Group Topic description: |- Sets the topic for the private channel. The topic is displayed next to the room name in the header. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.setTopic parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. example: ByehQjC44FwMeiLbX topic: type: string description: Enter the group's topic. example: QA discussions required: - roomId - topic examples: Example: value: roomId: ByehQjC44FwMeiLbX topic: Discuss all of the testing responses: '200': description: OK content: application/json: schema: type: object properties: topic: type: string success: type: boolean examples: Success: value: topic: Testing out everything. success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The bodyParam "topic" is required Example 2: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setType: post: tags: - Groups summary: Set Group Type description: |- Set the room type. The group type can be either `c` (public) or `p` (private). Any of the following permissions are required: * `create-c`: This permission is required if you are changing a private channel to a public channel. * `create-p`: This permission is required if you are changing a public channel to a private room. * `create-team-channel`: This permission is required if you are changing a team's private channel to a public channel. * `create-team-group`: This permission is required if you are changing a team's public channel to a private room. For ABAC-managed private rooms, changing the type from `p` to `c` is rejected with `error-action-not-allowed`. When the type changes to `c` (public) and the group has ABAC attributes, all ABAC attributes on the group are cleared as part of the conversion. ### Changelog | Version | Description | | ------- | ----------- | | 8.5.0 | Added ABAC behavior for `p` -> `c`: ABAC-managed private rooms are rejected, and successful conversions to public clear group ABAC attributes. | | 0.49.0 | Added | operationId: post-api-v1-groups.setType parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: |- The group ID. You can find the IDs by using any of the following endpoints: * Get List of User Groups: This endpoint returns all private channels in the workspace, if you have the required permissions to view them. * Get Groups: This endpoint returns the private channels that you are a member of. type: type: string description: Enter the group type. required: - roomId - type examples: Example: value: roomId: ByehQjC44FwMeiLbX type: c responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string name: type: string t: type: string msgs: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean sysMes: type: boolean _updatedAt: type: string usernames: type: array items: type: string joinCodeRequired: type: boolean muted: type: array items: type: object success: type: boolean examples: Example: value: group: _id: ByehQjC44FwMeiLbX name: testing0 t: c msgs: 0 u: _id: aiPqNoGkjpNDiRx6d username: goose160 ts: '2017-01-05T18:02:50.754Z' ro: false sysMes: true _updatedAt: '2017-01-05T19:02:24.429Z' usernames: - goose160 - graywolf336 joinCodeRequired: true muted: [ ] success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string action: type: string examples: 'Missing body param: type': value: success: false error: The bodyParam "type" is required ABAC-managed room conversion blocked: value: success: false error: 'Changing an ABAC managed private room to public is not allowed [error-action-not-allowed]' errorType: error-action-not-allowed details: method: saveRoomSettings action: Change_Room_Type '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.unarchive: post: tags: - Groups summary: Unarchive Group description: |- Unarchive a private channel. Permission required: `unarchive-room` ### Changelog | Version | Description | | ------- | ----------- | | 0.48.0 | Added | operationId: post-api-v1-groups.unarchive parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - roomId properties: roomId: type: string example: ByehQjC44FwMeiLbX description: The room ID that you want to unarchive. responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.files: get: tags: - Groups summary: Get Group Files description: |- Get all media files shared in a private channel. ### Changelog | Version | Description | | ------- | ----------- | | 0.64.0 | Change userId to user object in response | | 0.59.0 | Added | operationId: get-api-v1-groups.files parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/Optional-RoomName' - $ref: '#/components/parameters/Optional-RoomId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filterTypeGroup' - $ref: '#/components/parameters/filterName' responses: '200': description: OK content: application/json: schema: type: object properties: files: type: array items: type: object properties: _id: type: string name: type: string size: type: integer type: type: string rid: type: string description: type: string store: type: string complete: type: boolean uploading: type: boolean extension: type: string progress: type: integer user: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string instanceId: type: string etag: type: string path: type: string token: type: string uploadedAt: type: string url: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Example: value: files: - _id: S78TNnvaWGwdYRaCD name: images.jpeg size: 9778 type: image/jpeg rid: GENERAL description: '' store: 'GridFS:Uploads' complete: true uploading: false extension: jpeg progress: 1 user: _id: ksKsKmrjvxzkzxkww username: rocket.cat name: Rocket Cat _updatedAt: '2018-03-08T14:47:37.003Z' instanceId: uZG54xuoKauKHykbQ etag: jPaviS9qG22xC5sDC path: '/ufs/GridFS:Uploads/S78TNnvaWGwdYRaCD/images.jpeg' token: 28cAb868d9 uploadedAt: '2018-03-08T14:47:37.295Z' url: '/ufs/GridFS:Uploads/S78TNnvaWGwdYRaCD/images.jpeg' count: 1 offset: 0 total: 1 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: |- must have required property 'roomId' must have required property 'roomName' must match exactly one schema in oneOf errorType: error-invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.setEncrypted: post: tags: - Groups summary: Set Group as Encrypted description: |- Set a private channel as encrypted. Learn about end-to-end encryption here. Permission required: `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 3.13.0 | Added | operationId: post-api-v1-groups.setEncrypted parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: encrypted: type: boolean description: Whether or not to encrypt the room. roomId: type: string description: The group ID. Alternatively, use the `roomName` parameter and enter the group name. required: - encrypted - roomId examples: Example: value: encrypted: false roomId: JZ8Y2dLfYhsg323Rf responses: '200': description: OK content: application/json: schema: type: object properties: group: type: object properties: _id: type: string fname: type: string description: type: string broadcast: type: boolean encrypted: type: boolean teamMain: type: boolean name: type: string t: type: string msgs: type: integer usersCount: type: integer u: type: object properties: _id: type: string username: type: string ts: type: string ro: type: boolean teamId: type: string _updatedAt: type: string success: type: boolean examples: Success: value: group: _id: JZ8Y2dLfYhsg323Rf fname: test description: '' broadcast: false encrypted: false teamMain: true name: test t: p msgs: 0 usersCount: 1 u: _id: d26x6zSkaPSe5gCyy username: rodriq ts: '2021-10-22T11:59:17.029Z' ro: false teamId: 6172a795c563fc000acc4629 _updatedAt: '2021-10-22T12:00:11.496Z' success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid RoomId or RoomName: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found No RoomId or Roomname: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.convertToTeam: post: tags: - Groups summary: Convert a Group to Team description: |- Convert a private channel to a team. Permissions required: `create-team`, `edit-room` ### Changelog | Version | Description | | ------- | ----------- | | 3.13.0 | Added | operationId: post-api-v1-groups.convertToTeam parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - roomId properties: roomId: type: string description: Enter the private channel that you want to convert to a private team. example: JZ8Y2dLfYhsg323Rf examples: Example 1: value: roomId: JZ8Y2dLfYhsg323Rf responses: '200': description: OK content: application/json: schema: type: object properties: team: type: object properties: _id: type: string name: type: string type: type: integer createdAt: type: string createdBy: type: object properties: _id: type: string username: type: string _updatedAt: type: string roomId: type: string success: type: boolean examples: Success: value: team: _id: 6172b15bc563fc000acc462e name: ddd type: 1 createdAt: '2021-10-22T12:40:59.928Z' createdBy: _id: d26x6zSkaPSe5gCyy username: rod _updatedAt: '2021-10-22T12:40:59.928Z' roomId: h3HLZkQdrWCPg2RN7 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Team name exists: value: success: false error: team-name-already-exists Room name is required: value: success: false error: The parameter "roomId" or "roomName" is required Room not found: value: success: false error: 'The required "roomId" or "roomName" param provided does not match any group [error-room-not-found]' errorType: error-room-not-found '401': $ref: '#/components/responses/authorizationError' /api/v1/groups.roles: get: tags: - Groups summary: List Group Roles description: |- List all the roles of users in the private channel. ### Changelog | Version | Description | | ------- | ----------- | | 0.65.0 | Added | operationId: get-api-v1-groups.roles parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: 67ade8ef57422a89b02e2ce3 in: query name: roomId description: 'Enter the private channel ID. Alternatively, you can use the `roomName` parameter and enter the private channel''s name.' required: true responses: '200': description: OK content: application/json: schema: type: object properties: roles: type: array items: type: object properties: rid: type: string u: type: object properties: _id: type: string username: type: string name: type: string roles: type: array items: type: string _id: type: string success: type: boolean examples: Example: value: roles: - rid: BaE62jfDLXK3Xo6BA u: _id: BkNkw3iKgNyhMbPyW username: ronnie.dio name: Ronnie James Dio roles: - moderator _id: ehPuGyZBedznJsQHp success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: 'The parameter "roomId" or "roomName" is required [error-room-param-not-provided]' errorType: error-room-param-not-provided '401': $ref: '#/components/responses/authorizationError' /api/v1/directory: get: tags: - Directory summary: Directory description: |- Search workspace directory for users, channels and teams. ### Changelog | Version | Description | | ------- | ----------- | | 8.9.0 | Changed the rate limit to 100 requests every 100 seconds per client IP addres. | | 7.0.0 | Added `type`, `workspace` and `text` query parameters | | 1.0.0 | Added workspace query param | | 0.65.0 | Added Pagination fields: count, total, offset | | 0.64.0 | Added | operationId: get-api-v1-directory parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: text in: query description: The search term to be filtered schema: type: string example: "rocket" - name: type in: query description: |- It can be `channels` or `users`. When `type` is users you can send an additional workspace field, that can be local (default) or all. Workspace=all will work only if federation is enabled. schema: type: string example: "users" - name: workspace in: query description: It can be `local` or `all`( if federation is enabled). It is `local` by default. schema: type: string example: "local" - name: query in: query description: 'The query to search the workspace directory. When `type` is users you can send an additional workspace field, that can be local (default) or all. Workspace=all will work only if federation is enabled.' required: true schema: example: '{"text": "rocket", "type": "users", "workspace": "local"}' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' responses: '200': description: OK content: application/json: schema: type: object properties: result: type: array items: type: object properties: _id: type: string createdAt: type: string emails: type: array items: type: object properties: address: type: string verified: type: boolean name: type: string username: type: string avatarETag: type: string count: type: integer offset: type: integer total: type: integer success: type: boolean examples: Success: value: result: - _id: jRca8kibJx8NkLJxt createdAt: '2018-04-13T12:46:26.517Z' emails: - address: user.test.1523623548558@rocket.chat verified: false name: EditedRealNameuser.test.1523623548558 username: editedusernameuser.test.1523623548558 avatarETag: 6YbLtc4v9b4conXon count: 1 offset: 0 total: 1 success: true '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.open: post: tags: - Rooms summary: Open a Room description: |- Marks a room as "open" for the user, i.e. removes it from the user's list of hidden rooms and puts it back in the sidebar. operationId: post-api-v1-rooms.open parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string description: The ID of the room to open. required: - roomId examples: Example: value: roomId: GENERAL responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Missing roomId: value: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.hide: post: summary: Hide Room tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean x-examples: Example 1: success: true examples: Example 1: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string x-examples: Example 1: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params examples: Error due to missing roomId: value: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params Room already hidden error: value: success: false error: error-room-already-hidden '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: unauthorized examples: Example 1: value: success: false error: unauthorized operationId: post-api-v1-rooms.hide parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: roomId: type: string x-examples: Example 1: roomId: 6759dea438288929cff551c examples: Request body with roomId: value: roomId: 6759dea438288929cff551c description: | Hide rooms without restrictions based on type. You can only hide a room if you have access to it. ### Changelog | Version | Description | | ------- | ------------------------------------ | | 7.4.0 | Added | /api/v1/findOrCreateInvite: post: tags: - Room Invites summary: Find or Create Invite description: |- Creates or return an existing invite with the specified parameters. Permission required: `create-invite-links` operationId: post-api-v1-findOrCreateInvite parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: rid: type: string description: The room ID that the invite is being created for. days: type: integer description: The number of days that the invite will be valid for. Send `0` for unlimited. maxUses: type: integer description: The number of times that the invite can be used. Send `0` for unlimited. required: - rid - days - maxUses examples: Example: value: rid: csFYrDeixJG7PnrAh days: 10 maxUses: 0 responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: _id: type: string days: type: integer maxUses: type: integer rid: type: string userId: type: string createdAt: type: string expires: type: string nullable: true uses: type: integer _updatedAt: type: string examples: Success: value: - _id: kDKQ3H days: 1 maxUses: 1 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:31:56.774Z' expires: '2019-12-21T03:31:56.774Z' uses: 1 _updatedAt: '2019-12-20T03:33:40.065Z' - _id: 99ScEP days: 1 maxUses: 0 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:38:20.485Z' expires: '2019-12-21T03:38:20.485Z' uses: 0 _updatedAt: '2019-12-20T03:38:20.485Z' - _id: Y5JKM4 days: 0 maxUses: 1 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:38:25.313Z' expires: null uses: 1 _updatedAt: '2019-12-20T03:38:40.116Z' '401': $ref: '#/components/responses/authorizationError' /api/v1/rooms.roles: get: summary: Get Room Roles tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: roles: type: array items: type: object properties: _id: type: string rid: type: string u: type: object properties: _id: type: string username: type: string name: type: string roles: type: array items: type: string success: type: boolean examples: Example 1: value: roles: - _id: 668c75b2b319fc80bf0ed3a1 rid: 658282732dd9f928ad989e98 u: _id: P2dgWPPw5veigwcdK username: jane.doe name: Jane Doe roles: - moderator - _id: 6819edfa30c9c71254e45d18 rid: 658282732dd9f928ad989e98 u: _id: 74HrDgvTTxT56o8R8 username: mary.shelley name: Mary Shelley roles: - leader - _id: 668c7717b319fc80bf0ed3b0 rid: 658282732dd9f928ad989e98 u: _id: qHWhoJwwgk4bwcoNq username: test.user roles: - moderator - _id: 6690c37ab319fc80bf0ed407 rid: 658282732dd9f928ad989e98 u: _id: C38WSSzrGd2NCjzqJ username: test.cat roles: - owner success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean errorType: type: string error: type: string examples: Example 1: value: success: false errorType: error-invalid-params error: must have required property 'rid' '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-rooms.roles description: |- Get the list of roles in a specific room. This endpoint returns users with the `Owner`, `Leader`, and `Moderator` room roles. You can refer to the Roles user guide for more details on roles in Rocket.Chat. ### Changelog | Version | Description | | ------- | ------------------------------------ | | 7.10.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: 658282732dd9f928ad989e98 in: query name: rid description: Enter the room ID for which you want to view the room roles. required: true /api/v1/rooms.isMember: get: summary: Check Room Member tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: isMember: type: boolean success: type: boolean examples: Example 1: value: isMember: true success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: User not available in room: value: success: false error: error-user-not-found Missing user ID parameter: value: success: false error: |- must have required property 'userId' must have required property 'username' must match exactly one schema in oneOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-rooms.isMember description: 'Use this endpoint to check whether or not a user is a member of a specific room. If the user is not a member of the room, an error response (`error-user-not-found`) is returned. You can only get the results for the rooms that you are a member of. Otherwise, you get a forbidden error response.' parameters: - schema: type: string in: query name: roomId description: Enter the room ID in which you want to check for the user. required: true - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string in: query name: userId description: 'Enter the user ID that you want to check. Alternatively, you can use the `username` parameter and provide the user name instead of the user ID.' required: true /api/v1/rooms.autocomplete.channelAndPrivate.withPagination: get: summary: Autocomplete Room Name With Pagination tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string fname: type: string name: type: string t: type: string total: type: integer success: type: boolean examples: Example 1: value: items: - _id: 66c82e1e237405fc05fc1ef4 fname: api-team name: api-team t: c - _id: 66c88dae237405fc05fc1f06 fname: api-team2 name: api-team2 t: p total: 4 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Example 1: value: success: false error: The 'selector' param is required '401': $ref: '#/components/responses/authorizationError' operationId: get-api-v1-rooms.autocomplete.channelAndPrivate.withPagination description: 'List the public and private rooms whose names match a given string, excluding discussions, DMs, and omnichannel rooms. The endpoint is valuable when performing search operations. It returns only rooms that the user belongs to. This endpoint includes pagination query parameters.' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' - schema: type: string example: '{"name":"api"}' in: query name: selector description: The search term to be completed. It only applies to the room name. required: true '/api/v1/rooms.media/{rid}': post: summary: Upload Media Files to a Room tags: - Rooms responses: '200': description: OK headers: { } content: application/json: schema: type: object properties: file: type: object properties: _id: type: string url: type: string success: type: boolean examples: Example: value: file: _id: 67109d6c25682c7469486008 url: /file-upload/67109d6c25682c7469486008/Screenshot%202024-10-15%20at%2010.17.39.png success: true operationId: post-api-v1-rooms.media description: |- Only users who have access to send messages in a room can upload files there. You can't upload any file that exceeds the configured [Maximum File Upload Size](https://docs.rocket.chat/docs/file-upload#general-file-upload-settings1). To upload media files to a room, follow these steps: 1. Call this endpoint first. This endpoint uploads the file to the database and returns a file object with the file ID and URL data. Save the file ID, you will need this to send the file in the next step. 2. To send the file to a room, use the Send Uploaded File to a Room endpoint. The upload is temporary and expires 24 hours after this call. If you don't confirm it within that window, it is discarded and never appears in the room. parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file to upload. content: type: string description: A JSON-encoded object containing additional metadata for the uploaded file. parameters: - schema: type: string example: 674eca3e43725ce31dd9a2e8 name: rid in: path required: true description: The ID of the room where the file will be uploaded. '/api/v1/rooms.mediaConfirm/{rid}/{fileId}': parameters: - schema: type: string example: 66cd971f6fcbb8e8b3cf8e69 name: rid in: path required: true description: The ID of the room where the file will be sent. - schema: type: string example: 69424442ddfe6ceaf280f93f name: fileId in: path required: true description: The file ID you get from the Upload Files to a Room endpoint. post: summary: Send Uploaded File to a Room tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: message: type: object properties: _id: type: string rid: type: string ts: type: string msg: type: string file: type: object properties: _id: type: string name: type: string type: type: string size: type: integer format: type: string files: type: array items: type: object properties: _id: type: string name: type: string type: type: string size: type: integer format: type: string attachments: type: array items: type: object properties: title: type: string title_link: type: string title_link_download: type: boolean image_dimensions: type: object properties: width: type: integer height: type: integer image_preview: type: string image_url: type: string image_type: type: string image_size: type: integer type: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string urls: type: array items: type: object properties: {} success: type: boolean examples: Example 1: value: message: _id: 2ZABtFgt89fYYSw3Q rid: GENERAL ts: '2025-12-17T05:49:55.825Z' msg: '' file: _id: 69424442ddfe6ceaf280f93f name: 44.jpg type: image/jpeg size: 71224 format: jpeg files: - _id: 69424442ddfe6ceaf280f93f name: 44.jpg type: image/jpeg size: 71224 format: jpeg - _id: 69424483ddfe6ceaf280f941 name: thumb-44.jpg type: image/jpeg size: 13473 format: jpeg attachments: - title: 44.jpg title_link: /file-upload/69424442ddfe6ceaf280f93f/44.jpg title_link_download: true image_dimensions: width: 368 height: 360 image_preview: /9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQgsW+OGY6OKR5o3hGJfr6n3n5JkvPdSpXal1BmuoReom//Z image_url: /file-upload/69424483ddfe6ceaf280f941/44.jpg image_type: image/jpeg image_size: 71224 type: file u: _id: C38WSSzrGd2NCjzqJ username: test.cat name: test cat _updatedAt: '2025-12-17T05:49:55.959Z' urls: [] success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Example 1: value: success: false error: '[invalid-file]' errorType: invalid-file '401': $ref: '#/components/responses/authorizationError' operationId: post-api-v1-rooms.mediaConfirm-rid-fileId description: |- Use this endpoint to send an uploaded file to a room. You can use this endpoint only after calling the Upload Media Files to a Room endpoint and getting the file ID. Call it within 24 hours of the upload, using the same user account and room that uploaded the file. Otherwise, the request fails with `invalid-file`. parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: description: type: string description: Enter a file description. example: file description fileName: type: string description: Overrides the file name stored during upload. example: renamed-file.jpg fileContent: type: object description: Overrides the file content stored during upload. emoji: type: string description: The emoji you enter will be displayed as the avatar when the message is sent. example: ':one:' groupable: type: boolean description: Whether or not multiple messages can be grouped. msg: type: string description: Enter a message to be sent with the file. example: hello world tmid: type: string description: 'If you want to send the file to a thread, enter the thread ID here.' example: ZSnsznbWKqppnRny5 avatar: type: string description: Enter the avatar that will be displayed when the message is sent. You need the `message-impersonate` permission. example: 'https://picsum.photos/200' alias: type: string description: Enter the alias that will be used instead of your username when sending the message. You need the `message-impersonate` permission. example: test user customFields: type: string description: Enter custom fields if you have defined them in the Message settings. example: '{\"priority\": \"low\"}' examples: Example: value: alias: test avatar: 'https://picsum.photos/200' description: file upload description parameter groupable: false msg: file upload message parameter customFields: '{"priority": "low"}' emoji: ':one:' tmid: ZSnsznbWKqppnRny5 /api/v1/uploads.delete: post: summary: Delete Uploaded File tags: - Rooms responses: '200': description: OK content: application/json: schema: type: object properties: deletedFiles: type: array items: type: string success: type: boolean examples: Example 1: value: deletedFiles: - 699e6b8a8eddae7c5eaed9c3 - 699e6b8b8eddae7c5eaed9c5 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean errorType: type: string error: type: string examples: Example 1: value: success: false errorType: invalid-params error: must have required property 'fileId' '401': $ref: '#/components/responses/authorizationError' operationId: post-api-v1-uploads.delete description: |- Delete a specific file uploaded to a room. The response includes the list of files that were successfully removed. It may include additional files such as image thumbnails. Users can delete messages only in the following cases: * The **Allow Message Deleting** setting is enabled in the workspace's **Message** settings. * If the `Block Message Deleting After (n) Minutes` message setting has a non-zero value, the `bypass-time-limit-edit-and-delete` permission is required to delete messages after the defined time limit. * In read-only rooms, the `post-readonly` permission is required to delete messages. * The `delete-own-message` permission is required to delete users' own messages. * The `delete-message` permission is required for users to delete messages from other users. ### Changelog | Version | Description | | ------- | ----------- | | 8.2.0 | Added | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object required: - fileId properties: fileId: type: string description: Enter the file ID of the file that you want to delete. You can get this value from the Get Room Images endpoint. example: 699e6b8a8eddae7c5eaed9c3 examples: Example 1: value: fileId: 699e6b8a8eddae7c5eaed9c3 /api/v1/listInvites: get: tags: - Room Invites summary: List Invites description: |- Lists all of the invites on the workspace. Permission required: `create-invite-links` operationId: get-api-v1-listInvites responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: _id: type: string days: type: integer maxUses: type: integer rid: type: string userId: type: string createdAt: type: string expires: type: string nullable: true uses: type: integer _updatedAt: type: string examples: Success: value: - _id: kDKQ3H days: 1 maxUses: 1 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:31:56.774Z' expires: '2019-12-21T03:31:56.774Z' uses: 1 _updatedAt: '2019-12-20T03:33:40.065Z' - _id: 99ScEP days: 1 maxUses: 0 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:38:20.485Z' expires: '2019-12-21T03:38:20.485Z' uses: 0 _updatedAt: '2019-12-20T03:38:20.485Z' - _id: Y5JKM4 days: 0 maxUses: 1 rid: s7CE842q9WtvLctD7 userId: sNiDqHit5nGAGFg8X createdAt: '2019-12-20T03:38:25.313Z' expires: null uses: 1 _updatedAt: '2019-12-20T03:38:40.116Z' '401': $ref: '#/components/responses/authorizationError' /api/v1/removeInvite/{_id}: delete: tags: - Room Invites summary: Delete Invite by ID description: "Deletes an invite from the workspace.\r\n\r\nPermission required: `create-invite-links`" operationId: delete-api-v1-removeInvite-_id parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - name: _id in: path description: The invite ID to be deleted. required: true schema: type: string example: kDKQ3H responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string details: type: object properties: method: type: string examples: Invalid Invitation Id: value: success: false error: 'Invalid Invitation _id [invalid-invitation-id]' errorType: invalid-invitation-id details: method: removeInvite '401': $ref: '#/components/responses/authorizationError' /api/v1/useInviteToken: post: tags: - Room Invites summary: Use Invite Token description: |- Uses an invite token to join a channel or room. This endpoint also checks whether the user is banned from the target room before allowing them to use the invite link. A banned user must be unbanned first before they can join via an invite token. ### Changelog | Version | Description | |---------|--------| | 8.4.0 | Added ban check — banned users can no longer join via invite token | operationId: post-useInviteToken parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: type: object properties: token: type: string description: The invite token to use. required: - token examples: Use Invite Token: value: token: R4VDXJ9KJZB8M2QW responses: '200': description: OK content: application/json: schema: type: object properties: room: type: object description: The room information. properties: _id: type: string name: type: string topic: type: string success: type: boolean examples: Success Example: value: room: _id: sN9KJZX2aX7aXqB2a name: general topic: General discussion success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: User Is Banned: value: success: false error: User is banned from this room errorType: error-user-is-banned Invalid Token: value: success: false error: Invalid invite token errorType: error-invalid-token Token Expired: value: success: false error: Invite token has expired errorType: error-invite-token-expired '401': $ref: '#/components/responses/authorizationError' '/api/v1/abac/rooms/:rid/attributes': post: summary: Replace room ABAC attributes tags: - ABAC responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: ABAC not enabled: value: success: false error: error-abac-not-enabled Attribute definition missing: value: success: false error: error-attribute-definition-not-found Invalid attribute values: value: success: false error: error-invalid-attribute-values '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: post-abac-rooms-rid-attributes parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' description: |-

- Replaces the full ABAC attribute set for a room. - Sets the complete set of ABAC attributes on the specified room by providing an attributes object that maps attribute keys to arrays of allowed values; any previously assigned attributes not included in the request are removed. - Requires the ABAC license, the `abac-management` and `manage-abac-admin-rooms` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | requestBody: content: application/json: schema: type: object examples: Example 1: value: attributes: department: - it - sales region: - asia - europa delete: summary: Delete all ABAC attributes tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Room not found: value: success: false error: error-room-not-found '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: delete-abac-rooms-rid-attributes parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' description: |-

- Clears all ABAC attributes from a room. - Removes every ABAC attribute key and value currently assigned to the specified room, leaving it with no ABAC attributes configured. - Requires the `abac-management` and `manage-abac-admin-rooms` permissions. This call does not require the global setting `ABAC_Enabled` to be on, so attributes can be cleared after disabling ABAC. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | parameters: [] '/api/v1/abac/rooms/:rid/attributes/:key': post: summary: Add ABAC attribute key to room tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: ABAC not enabled: value: success: false error: error-abac-not-enabled Attribute definition missing: value: success: false error: error-attribute-definition-not-found Invalid attribute values: value: success: false error: error-invalid-attribute-values Duplicate key on a room: value: success: false error: error-duplicate-attribute-key Cannot convert default room to ABAC: value: success: false error: error-cannot-convert-default-room-to-abac Room not found: value: success: false error: error-room-not-found '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: post-abac-rooms-rid-attributes-key description: |-

- Adds a single ABAC attribute key to a room. - Creates a new ABAC attribute on the specified room for the given key, assigning it the provided values array; fails if the room already has this key or if the key/values are not allowed by the global attribute definition. - Requires the ABAC license, the `abac-management` and `manage-abac-admin-rooms` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: values: type: array items: type: string examples: Example 1: value: values: - asia description: |- - Values (array of strings, required): The attribute values to assign for this key. - Must have at least 1 item, max 10 items, and all values must be unique. parameters: [] put: summary: Set room ABAC attribute values responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Attribute definition missing: value: success: false error: error-attribute-definition-not-found Invalid attribute values: value: success: false error: error-invalid-attribute-values Room not found: value: success: false error: error-room-not-found Cannot convert default room to ABAC: value: success: false error: error-cannot-convert-default-room-to-abac ABAC not enabled: value: success: false error: error-abac-not-enabled '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: put-abac-rooms-rid-attributes-key description: |-

- Sets the values of a single ABAC attribute on a room. - Replaces the existing values for the given attribute key on the specified room with the provided values array (or creates the attribute if it does not yet exist), enforcing the global attribute definition and ABAC validation rules. - Requires the ABAC license, the `abac-management` and `manage-abac-admin-rooms` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: values: type: array items: type: string examples: Example 1: value: values: - eng - sales - hr description: |- - Values (array of strings, required): The attribute values to assign for this key. - Must have at least 1 item, max 10 items, and all values must be unique. tags: - ABAC delete: summary: Delete room ABAC attribute key tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Room not found: value: success: false error: error-room-not-found '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: delete-abac-rooms-rid-attributes-key description: |-

- Removes a single ABAC attribute key from a room. - Deletes the specified attribute key and all its values from the room's ABAC configuration, leaving other attributes unchanged. - Requires the `abac-management` and `manage-abac-admin-rooms` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' /api/v1/abac/attributes: get: summary: List ABAC attribute definitions tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean attributes: type: array items: type: object properties: _id: type: string key: type: string values: type: array items: type: string offset: type: integer count: type: integer total: type: integer examples: Success: value: success: true attributes: - _id: 69778264070f6083845051e6 key: departmentNumber values: - department - _id: 697ca091070f60838450580d key: my_department values: - eng - sales - hr - it offset: 0 count: 25 total: 5 '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Invalid query: value: success: false error: error-invalid-query-parameters '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: get-abac-attributes description: |-

- Lists all ABAC attribute definitions. - Returns a paginated list of attribute definitions (key and allowed values). - Supports optional filtering by attribute key or value, and pagination via offset and count query parameters. - Requires the `abac-management` and `manage-abac-admin-room-attributes` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - schema: type: number in: query name: offset description: 'Pagination offset (default: 0)' - schema: type: number in: query name: count description: 'Number of items per page (default: 25)' - schema: type: string in: query name: key description: Filter attribute definitions by key (case-insensitive match) - schema: type: string in: query name: values description: Filter attribute definitions by values (case-insensitive match) - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' post: summary: Create ABAC attribute definition tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: ABAC disabled: value: success: false error: error-abac-not-enabled Invalid attribute values: value: success: false error: error-invalid-attribute-values Invalid attribute key: value: success: false error: error-invalid-attribute-key Duplicate attribute key: value: success: false error: error-duplicate-attribute-key '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: post-abac-attributes description: |-

- Creates a new ABAC attribute definition. - Registers a global ABAC attribute by specifying its key and the list of allowed values, making it available for use on rooms and users. - Requires the ABAC license, the `abac-management` and `manage-abac-admin-room-attributes` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object properties: key: type: string values: type: array items: type: string examples: Example 1: value: key: my_department values: - eng - sales - hr - it parameters: [] /api/v1/abac/users/sync: post: summary: Sync users ABAC attributes from LDAP tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request headers: {} content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: ABAC disabled: value: success: false error: error-abac-not-enabled Invalid body (schema validation): value: success: false error: error-invalid-body-params '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: post-abac-users-sync description: |-

- Syncs ABAC attributes for specified users from LDAP. - Refreshes user ABAC attributes by reading current data from LDAP and applying the configured LDAP → ABAC attribute mapping. - Users can be identified by usernames, ids, emails, or ldapIds. - Requires the LDAP Enterprise and ABAC licenses, the `abac-management` and `manage-abac-admin-room-attributes` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: description: |- At least one of these properties is required: - usernames (string[]) — Array of Rocket.Chat usernames (1–100 items, unique) - ids (string[]) — Array of Rocket.Chat user IDs (1–100 items, unique) - emails (string[]) — Array of email addresses (1–100 items, unique) - ldapIds (string[]) — Array of LDAP IDs (1–100 items, unique) content: application/json: schema: type: object properties: usernames: type: array items: type: string ids: type: array items: type: string emails: type: array items: type: string ldapIds: type: array items: type: string examples: Example 1: value: usernames: - alice ids: - userId1 emails: - bob@example.com ldapIds: - ldapId123 parameters: [] '/api/v1/abac/attributes/:_id': put: summary: Update ABAC attribute definition tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: ABAC disabled: value: success: false error: error-abac-not-enabled Attribute not found: value: success: false error: error-attribute-not-found Attribute in use (cannot rename key / cannot remove used values): value: success: false error: error-attribute-in-use Invalid values (e.g. empty values): value: success: false error: error-invalid-attribute-values Duplicate attribute key (renaming to an existing key): value: success: false error: error-duplicate-attribute-key '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: 'put-abac-attributes-:_id' description: |-

- Updates an existing ABAC attribute definition. - Modifies the attribute identified by `_id`, allowing you to rename its key, change its list of allowed values, or both, subject to in-use and validation checks. - Requires the ABAC license, the `abac-management` and `manage-abac-admin-room-attributes` permissions, and the global setting `ABAC_Enabled` to be turned on. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: type: object x-examples: Example 1: key: my_department values: - eng - sales required: - key - values properties: key: type: string example: my_department values: type: array items: type: string example: - eng - sales get: summary: Get ABAC attribute definition by ID tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean key: type: string values: type: array items: type: string examples: Success: value: success: true key: my_department values: - eng - sales - hr - it '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Attribute not found: value: success: false error: error-attribute-not-found '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: 'get-abac-attributes-:_id' description: |-

- Retrieves a single ABAC attribute definition by ID. - Returns the attribute key and its allowed values for the definition identified by `_id`. - Requires the `abac-management` and `manage-abac-admin-room-attributes` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' delete: summary: Delete ABAC attribute definition by ID tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Attribute not found: value: success: false error: error-attribute-not-found Attribute in use: value: success: false error: error-attribute-in-use '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-not-authorized examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: 'delete-abac-attributes-:_id' description: |-

- Deletes an ABAC attribute definition by ID. - Removes the attribute definition identified by `_id`. The delete fails if the attribute is currently in use, for example assigned to any room. - Requires the `abac-management` and `manage-abac-admin-room-attributes` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' parameters: [] '/api/v1/abac/attributes/:key/is-in-use': get: summary: Check if ABAC attribute is in use tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean inUse: type: boolean x-examples: Example 1: success: true inUse: true examples: Success: value: success: true inUse: true '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-unauthorized examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-not-authorized examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: 'get-abac-attributes-:key-is-in-use' description: |-

- Checks whether an ABAC attribute definition is currently used by any room. - Requires the `abac-management` and `manage-abac-admin-room-attributes` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-room-attributes` granular permission requirement. | parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' parameters: [] /api/v1/abac/rooms: get: summary: List rooms with ABAC attributes tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean rooms: type: array items: type: object properties: _id: type: string name: type: string t: type: string abacAttributes: type: array items: type: object properties: key: type: string values: type: array items: type: string offset: type: integer count: type: integer total: type: integer x-examples: Example 1: success: true rooms: - _id: ROOM_ID name: private-room t: p abacAttributes: - key: my_department values: - eng - sales offset: 0 count: 25 total: 1 examples: Success: value: success: true rooms: - _id: ROOM_ID name: private-room t: p abacAttributes: - key: my_department values: - eng - sales offset: 0 count: 25 total: 1 '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-invalid-query-parameters examples: Invalid query: value: success: false error: error-invalid-query-parameters '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-unauthorized examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-not-authorized examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: get-abac-rooms description: |-

- Lists rooms with ABAC attributes. - Returns a paginated list of rooms that have ABAC attributes configured, with optional filtering by room name, attribute key, or attribute value using the `filter` and `filterType` query parameters. - Requires the `abac-management` and `manage-abac-admin-rooms` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-rooms` granular permission requirement. | parameters: - schema: type: number in: query name: offset description: Pagination offset (default 0) - schema: type: number in: query name: count description: Page size (default 25) - schema: type: string in: query name: filter description: Search text - schema: type: string in: query name: filterType description: 'One of: all, roomName, attribute, value' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' parameters: [] /api/v1/abac/audit: get: summary: List ABAC audit events tags: - ABAC responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean events: type: array items: type: object properties: _id: type: string t: type: string ts: type: string actor: type: object properties: _id: type: string username: type: string name: type: string data: type: object properties: {} offset: type: integer count: type: integer total: type: integer x-examples: Example 1: success: true events: - _id: EVENT_ID t: abac.object.attribute.changed ts: '2026-01-30T12:34:56.789Z' actor: _id: USER_ID username: admin name: Admin data: {} offset: 0 count: 25 total: 1 examples: Success: value: success: true events: - _id: EVENT_ID t: abac.object.attribute.changed ts: '2026-01-30T12:34:56.789Z' actor: _id: USER_ID username: admin name: Admin data: {} offset: 0 count: 25 total: 1 '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-invalid-query-parameters examples: Invalid query: value: success: false error: error-invalid-query-parameters '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-unauthorized examples: Unauthorized login attempt: value: success: false error: error-unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string x-examples: Example 1: success: false error: error-not-authorized examples: Missing required ABAC permissions: value: success: false error: error-not-authorized operationId: get-abac-audit description: |-

- Lists ABAC audit events. - Returns a paginated audit log of ABAC-related actions (attribute changes, room attribute changes/removals, and ABAC actions), filterable by time range (`start`, `end`) and optional `actor`, with optional sorting. - Requires the ABAC and Auditing licenses, the `abac-management` and `view-abac-admin-audit` permissions. ### Changelog | Version | Description | | ------- | ----------- | | 8.0.0 | Added | | 8.5.0 | Added the `view-abac-admin-audit` granular permission requirement. | parameters: - schema: type: string in: query name: start description: start of time range (defaults to epoch if omitted) - schema: type: string in: query name: end description: end of time range (defaults to now if omitted) - schema: type: string in: query description: Filter by actor fields name: actor - schema: type: number in: query name: offset description: Pagination offset (default 0) - schema: type: number in: query name: count description: Page size (default 25) - schema: type: string in: query name: sort description: 'Sorting, typically { "ts": -1 } or { "ts": 1 }' - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' parameters: [] /api/v1/abac/pdp/health: get: tags: - ABAC summary: Get PDP Health Status description: |-

Checks the health and availability of the configured Policy Decision Point (PDP) for Attribute-Based Access Control (ABAC). This endpoint is used by administrators to verify that the external PDP service is operational and properly configured. It includes rate limiting to prevent abuse. Permissions required: `abac-management` and `manage-abac-admin-settings`. ### Changelog | Version | Description | |---------|--------| | 8.0.0 | Added | | 8.5.0 | Added the `manage-abac-admin-settings` granular permission requirement. | | 8.4.0 | Added endpoint to check external PDP health status | operationId: get-abac-pdp-health parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' responses: '200': description: OK - PDP is available and healthy content: application/json: schema: type: object properties: available: type: boolean description: Indicates whether the PDP is available. enum: [true] message: type: string description: Health check message. success: type: boolean description: Indicates if the request was successful. examples: PDP Healthy: value: available: true message: ABAC_PDP_Health_OK success: true '400': description: Bad Request - PDP is unavailable or unhealthy content: application/json: schema: type: object properties: available: type: boolean description: Indicates whether the PDP is available. enum: [false] message: type: string description: Error message describing why the PDP is unavailable. success: type: boolean description: Indicates if the request was successful. examples: PDP Unavailable: value: available: false message: ABAC_PDP_Health_Not_OK success: false Connection Error: value: available: false message: Failed to connect to external PDP service success: false '401': $ref: '#/components/responses/authorizationError' '403': description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: You do not have permission to manage ABAC /api/v1/subscriptions.get: get: summary: Get All Subscriptions description: |- Get the room notification subscription details and the latest updates. Note that the unread counter value depends on your settings in the **Manage** > **Workspace** > **General** section. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added the `threadDrafts` field | |0.60.0 | Added | operationId: get-api-v1-subscriptions.get parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: '2017-11-25T15:08:17.248Z' in: query name: updatedSince description: 'Date and time from which to fetch changes. Format: ISO 8601 datetime. Optional seconds, optional milliseconds, optional timezone, always with colon time separators.' responses: '200': description: OK content: application/json: schema: type: object properties: update: type: array items: $ref: '#/components/schemas/Subscription' remove: type: array items: type: object success: type: boolean examples: Success Example: value: update: - t: c ts: '2017-11-25T15:08:17.249Z' name: general fname: null rid: GENERAL u: _id: EoyAmF4mxx5HxJHJB username: rocket.cat name: Rocket Cat open: true alert: true unread: 1 userMentions: 1 groupMentions: 0 _updatedAt: '2017-11-25T15:08:17.249Z' _id: 5ALsG3QhpJfdMpyc8 remove: [] success: true '401': $ref: '#/components/responses/authorizationError' tags: - Subscriptions /api/v1/subscriptions.getOne: get: summary: Get Subscription Room description: |- Get the notification subscription details for a specific room. Note that the unread counter value depends on your settings at the **Manage** > **Workspace** > **General** section. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added the `threadDrafts` field | |0.63.0 | Added | operationId: get-api-v1-subscriptions.getOne parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' - schema: type: string example: ByehQjC44FwMeiLbX in: query name: roomId description: The room ID. required: true responses: '200': description: OK content: application/json: schema: type: object properties: subscription: $ref: '#/components/schemas/Subscription' success: type: boolean x-examples: Success Example: subscription: _id: 65cdba92f581e473b5647051 open: true alert: true unread: 1 userMentions: 1 groupMentions: 0 ts: '2024-02-15T07:17:38.547Z' rid: GENERAL name: general t: c u: _id: fZ3bvXC72pobjFPLJ username: funke _updatedAt: '2024-07-02T18:07:35.267Z' ls: '2024-05-30T16:47:36.993Z' draft: Remember to share the report threadDrafts: 7aDSXtjMA3KPLxLjt: I will check this and reply success: true examples: Success Example: value: result: - _id: jRca8kibJx8NkLJxt createdAt: '2018-04-13T12:46:26.517Z' emails: - address: user.test.1523623548558@rocket.chat verified: false name: EditedRealNameuser.test.1523623548558 username: editedusernameuser.test.1523623548558 avatarETag: 6YbLtc4v9b4conXon count: 1 offset: 0 total: 1 success: true '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Parameter: value: success: false error: 'must have required property ''roomId'' [invalid-params]' errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' tags: - Subscriptions parameters: [] /api/v1/subscriptions.read: parameters: [] post: summary: Mark Channel as Read operationId: post-api-v1-subscriptions.read responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Parameter: value: success: false error: |- must have required property 'rid' must have required property 'roomId' must match a schema in anyOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: anyOf: - type: object required: ["roomId"] properties: roomId: type: string description: The room ID. example: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y readThreads: type: boolean - type: object required: ["rid"] properties: rid: type: string description: The room ID. example: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y readThreads: type: boolean examples: RoomId: value: roomId: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y Rid: value: rid: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y description: |- ### Changelog | Version | Description | | ---------------- | ------------| |3.11.0 | `roomId` can be used as argument instead of `rid`. | |0.61.0 | Added | tags: - Subscriptions /api/v1/subscriptions.unread: parameters: [] post: summary: Mark Channel as Unread operationId: post-api-v1-subscriptions.unread responses: '200': $ref: '#/components/responses/trueSuccess' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean error: type: string errorType: type: string examples: Invalid Parameter: value: success: false error: |- must have required property 'roomId' must have required property 'firstUnreadMessage' must match a schema in anyOf [invalid-params] errorType: invalid-params '401': $ref: '#/components/responses/authorizationError' parameters: - $ref: '#/components/parameters/Auth-Token' - $ref: '#/components/parameters/UserId' requestBody: content: application/json: schema: anyOf: - type: object required: ["roomId"] properties: roomId: type: string description: The room ID. - type: object required: ["firstUnreadMessage"] properties: firstUnreadMessage: type: object required: [" _id"] properties: _id: type: string description: The message ID. examples: Example : value: roomId: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y Example 2: value: firstUnreadMessage: _id: L6su9mxwdDkvdSaT9hvzu8z6mHFigiXy6Y description: '' description: |- Mark messages as unread by room ID or from a message. ### Changelog | Version | Description | | ---------------- | ------------| |0.65.0 | Added | tags: - Subscriptions tags: - name: Channels - name: Directory - name: Groups - name: Rooms - name: Teams - name: Room Invites - name: Subscriptions - name: ABAC components: schemas: Attachment: type: object properties: ts: type: string example: 1970-01-01T00:00:00.000Z title: type: string title_link: type: string title_link_download: type: boolean image_dimensions: type: object properties: width: type: integer example: 444 height: type: integer example: 360 image_preview: type: string example: /9j/2wBDAAYEBQ... image_url: type: string example: /file-upload/PNTaE9SBQasdpAwk2/img_1.jpg image_type: type: string example: image/jpeg image_size: type: integer example: 26674 type: type: string example: file description: type: string example: '' Subscription: type: object properties: _id: type: string open: type: boolean alert: type: boolean unread: type: integer userMentions: type: integer groupMentions: type: integer ts: type: string rid: type: string name: type: string fname: type: string nullable: true t: type: string u: type: object properties: _id: type: string username: type: string name: type: string _updatedAt: type: string ls: type: string E2EKey: type: string draft: type: string description: The unfinished message draft for the room. threadDrafts: type: object description: The unfinished thread reply drafts, keyed by the ID of each thread's main message. additionalProperties: type: string parameters: Optional-RoomId: name: roomId in: query description: The room ID. It is required if the `roomName` is not provided. schema: type: string example: dlpfuijw7ej Optional-RoomName: name: roomName in: query description: The room name. It is required if the `roomId` is not provided. required: false schema: type: string example: general RoomId: name: roomId in: query description: The room id. required: true schema: type: string example: jdiue8TGkodp Optional-TeamId: name: teamId in: query description: The team id. It is required if the `teamName` is not provided. schema: type: string example: 63f3efc4b000b6b6d86704b2 Optional-TeamName: name: teamName in: query description: The team name. It is required if the `teamId` is not provided. required: false schema: type: string example: livestream offset: name: offset in: query description: 'Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.' required: false schema: type: integer example: 50 count: name: count in: query description: 'The number of items to return. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.' required: false schema: type: integer example: 50 sort: name: sort in: query description: 'List of fields to order by, and in which direction. This is a JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {"value": -1, "_id": 1}. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.' required: false schema: { } query: name: query in: query description: 'This parameter allows you to use MongoDB query operators to search for specific data. For example, to query users with a name that contains the letter "g": `query={ "name": { "$regex": "g" } }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.' required: false schema: { } fields: name: fields in: query description: 'This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: `fields={ "username": 1 }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.' required: false schema: type: string Auth-Token: name: X-Auth-Token in: header description: The `authToken` of the authenticated user. required: true schema: type: string example: RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f UserId: name: X-User-Id in: header description: The `userId` of the authenticated user. required: true schema: type: string example: rbAXPnMktTFbNpwtJ filterName: name: name in: query description: The name of the file to search for. schema: type: string example: logo filterTypeGroup: name: typeGroup in: query description: |- Filter results by the type of file. Available options: - `all`: Return all file types. - `image`: Filter by image files. - `video`: Filter by video files. - `audio`: Filter by audio files. - `text`: Filter by text documents. - `application`: Filter by other file types. schema: type: string example: images responses: trueSuccess: description: OK content: application/json: schema: type: object properties: success: type: boolean examples: Success: value: success: true authorizationError: description: Unauthorized content: application/json: schema: type: object properties: status: type: string message: type: string examples: Authorization Error: value: status: error message: You must be logged in to do this. forbiddenError: description: Forbidden content: application/json: schema: type: object properties: success: type: boolean error: type: string examples: Permission Error: value: success: false error: 'User does not have the permissions required for this action [error-unauthorized]'