mirror of
https://github.com/hanzoai/team.git
synced 2026-09-30 01:57:35 +00:00
zeekayandHanzo Dev
404de134f3
The OpenAPI document keys every operation by its full path, so the spec described endpoints that no longer exist the moment the server moved. The openApiSync analyzer cross-checks each registered subrouter against that document and reconstructs the prefix from a literal of its own, so spec and analyzer have to move together or every route reports as missing. Its special case for the v5 root goes away with the root itself. The api/v4 directory keeps its name: it is where the spec sources live, not a URL anyone requests. Co-authored-by: Hanzo Dev <[email protected]>
1232 lines
37 KiB
YAML
1232 lines
37 KiB
YAML
/v1/team/groups:
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get groups
|
|
description: >
|
|
Retrieve a list of all groups not associated to a particular channel or
|
|
team.
|
|
|
|
|
|
If you use `not_associated_to_team`, you must be a team admin for that particular team (permission to manage that team).
|
|
|
|
|
|
If you use `not_associated_to_channel`, you must be a channel admin for that particular channel (permission to manage that channel).
|
|
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroups
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of groups per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: q
|
|
in: query
|
|
description: String to pattern match the `name` and `display_name` field. Will
|
|
return all groups whose `name` and `display_name` field match any of
|
|
the text.
|
|
schema:
|
|
type: string
|
|
- name: include_member_count
|
|
in: query
|
|
description: Boolean which adds the `member_count` attribute to each group JSON
|
|
object
|
|
schema:
|
|
type: boolean
|
|
- name: not_associated_to_team
|
|
in: query
|
|
description: Team GUID which is used to return all the groups not associated to
|
|
this team
|
|
schema:
|
|
type: string
|
|
- name: not_associated_to_channel
|
|
in: query
|
|
description: Group GUID which is used to return all the groups not associated to
|
|
this channel
|
|
schema:
|
|
type: string
|
|
- name: since
|
|
in: query
|
|
description: >
|
|
Only return groups that have been modified since the given Unix
|
|
timestamp (in milliseconds). All modified groups, including deleted
|
|
and created groups, will be returned.
|
|
|
|
__Minimum server version__: 5.24
|
|
schema:
|
|
type: integer
|
|
- name: filter_allow_reference
|
|
in: query
|
|
description: Boolean which filters the group entries with the `allow_reference` attribute set.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Create a custom group
|
|
description: |
|
|
Create a `custom` type group.
|
|
|
|
#### Permission
|
|
Must have `create_custom_group` permission.
|
|
|
|
__Minimum server version__: 6.3
|
|
operationId: CreateGroup
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- name
|
|
- display_name
|
|
- source
|
|
- allow_reference
|
|
- user_ids
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The unique group name used for at-mentioning.
|
|
display_name:
|
|
type: string
|
|
description: The display name of the group which can include spaces.
|
|
source:
|
|
type: string
|
|
description: Must be `custom`
|
|
allow_reference:
|
|
type: boolean
|
|
description: Must be true
|
|
user_ids:
|
|
type: array
|
|
description: The user ids of the group members to add.
|
|
items:
|
|
type: string
|
|
description: Group object and initial members.
|
|
required: true
|
|
responses:
|
|
"501":
|
|
description: |
|
|
Group has an invalid `source`, or
|
|
`allow_reference` is not `true`, or
|
|
group has a `remote_id`.
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"201":
|
|
description: Group creation and memberships successful.
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"/v1/team/groups/{group_id}":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get a group
|
|
description: |
|
|
Get group from the provided group id string
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroup
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Group retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
delete:
|
|
tags:
|
|
- groups
|
|
summary: Deletes a custom group
|
|
description: |
|
|
Soft deletes a custom group.
|
|
|
|
##### Permissions
|
|
Must have `custom_group_delete` permission for the given group.
|
|
|
|
__Minimum server version__: 6.3
|
|
operationId: DeleteGroup
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: The ID of the group.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
description: The group doesn't have a `source` value of `custom`.
|
|
"404":
|
|
description: Group is already deleted or doesn't exist.
|
|
"200":
|
|
description: Successfully deleted the group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"/v1/team/groups/{group_id}/patch":
|
|
put:
|
|
tags:
|
|
- groups
|
|
summary: Patch a group
|
|
description: >
|
|
Partially update a group by providing only the fields you want to
|
|
update. Omitted fields will not be updated. The fields that can be
|
|
updated are defined in the request body, all other provided fields will
|
|
be ignored.
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: PatchGroup
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
description: Group object that is to be updated
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Group patch successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/restore":
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Restore a previously deleted group.
|
|
description: >
|
|
Restores a previously deleted custom group, allowing it to be used normally.
|
|
|
|
May not be used with LDAP groups.
|
|
|
|
##### Permissions
|
|
Must have `restore_custom_group` permission for the given group.
|
|
|
|
__Minimum server version__: 7.7
|
|
operationId: RestoreGroup
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Group restored successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/teams/{team_id}/link":
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Link a team to a group
|
|
description: |
|
|
Link a team to a group.
|
|
|
|
##### Permissions
|
|
Requires `invite_user` on the target team, or `sysconsole_write_user_management_groups`.
|
|
If the group has `allow_reference` disabled, also requires `sysconsole_read_user_management_groups`.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: LinkGroupSyncableForTeam
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"201":
|
|
description: Team linked to group
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableTeam"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
delete:
|
|
tags:
|
|
- groups
|
|
summary: Unlink a team from a group
|
|
description: |
|
|
Delete a link between a team and a group.
|
|
|
|
##### Permissions
|
|
Requires `invite_user` on the target team, or `sysconsole_write_user_management_groups`.
|
|
If the group has `allow_reference` disabled, also requires `sysconsole_read_user_management_groups`.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: UnlinkGroupSyncableForTeam
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Team unlinked from group
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/channels/{channel_id}/link":
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Link a channel to a group
|
|
description: |
|
|
Link a channel to a group.
|
|
|
|
##### Permissions
|
|
Requires `manage_private_channel_members` (private channel) or
|
|
`manage_public_channel_members` (public channel) on the target channel.
|
|
If this is the group's first linkage into the channel's team context, also
|
|
requires `invite_user` on the team, or `sysconsole_write_user_management_groups`.
|
|
If the group has `allow_reference` disabled, also requires `sysconsole_read_user_management_groups`.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: LinkGroupSyncableForChannel
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"201":
|
|
description: Channel linked to group
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableChannel"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
delete:
|
|
tags:
|
|
- groups
|
|
summary: Unlink a channel from a group
|
|
description: |
|
|
Delete a link between a channel and a group.
|
|
|
|
##### Permissions
|
|
Requires `manage_private_channel_members` (private channel) or
|
|
`manage_public_channel_members` (public channel) on the target channel.
|
|
If unlinking would leave the group with no remaining linkage in that channel's team context (last/only linkage for that team), also
|
|
requires `invite_user` on the team, or `sysconsole_write_user_management_groups`.
|
|
If the group has `allow_reference` disabled, also requires `sysconsole_read_user_management_groups`.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: UnlinkGroupSyncableForChannel
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Channel unlinked from group
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/teams/{team_id}":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get a team syncable for a group
|
|
description: |
|
|
Get the GroupSyncableTeam object with the provided group and team identifiers.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupSyncableForTeamId
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Team syncable retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableTeam"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/channels/{channel_id}":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get a channel syncable for a group
|
|
description: |
|
|
Get the GroupSyncableChannel object with the provided group and channel identifiers.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupSyncableForChannelId
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Channel syncable retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableChannel"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/teams":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get team syncables for a group
|
|
description: |
|
|
Retrieve the list of team syncables associated with the group.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupSyncablesTeams
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Team syncables retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GroupSyncableTeams"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/channels":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get channel syncables for a group
|
|
description: |
|
|
Retrieve the list of channel syncables associated with the group.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupSyncablesChannels
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Channel syncables retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GroupSyncableChannels"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/teams/{team_id}/patch":
|
|
put:
|
|
tags:
|
|
- groups
|
|
summary: Patch a team syncable for a group
|
|
description: >
|
|
Partially update a GroupSyncableTeam by providing only the fields you want
|
|
to update. Omitted fields will not be updated.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: PatchGroupSyncableForTeam
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
description: GroupSyncableTeam object that is to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auto_add:
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
description: Team syncable patched
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableTeam"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/channels/{channel_id}/patch":
|
|
put:
|
|
tags:
|
|
- groups
|
|
summary: Patch a channel syncable for a group
|
|
description: >
|
|
Partially update a GroupSyncableChannel by providing only the fields you
|
|
want to update. Omitted fields will not be updated.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: PatchGroupSyncableForChannel
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
description: GroupSyncableChannel object that is to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auto_add:
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
description: Channel syncable patched
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupSyncableChannel"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/{group_id}/members":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get group users
|
|
description: |
|
|
Retrieve the list of users associated with a given group.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupUsers
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of groups per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
responses:
|
|
"200":
|
|
description: User list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
members:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
total_member_count:
|
|
type: integer
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
delete:
|
|
tags:
|
|
- groups
|
|
summary: Removes members from a custom group
|
|
description: |
|
|
Soft deletes a custom group members.
|
|
|
|
##### Permissions
|
|
Must have `custom_group_manage_members` permission for the given group.
|
|
|
|
__Minimum server version__: 6.3
|
|
operationId: DeleteGroupMembers
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: The ID of the group to delete.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
description: An object containing the user ids of the members to remove.
|
|
properties:
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
description: If the group does not have a `source` value of `custom`.
|
|
"404":
|
|
description: Can't find the group.
|
|
"200":
|
|
description: Successfully deleted the group members.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GroupMember"
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Adds members to a custom group
|
|
description: |
|
|
Adds members to a custom group.
|
|
|
|
##### Permissions
|
|
Must have `custom_group_manage_members` permission for the given group.
|
|
|
|
__Minimum server version__: 6.3
|
|
operationId: AddGroupMembers
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: The ID of the group.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
description: An object containing the user ids of the members to add.
|
|
properties:
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
description: If the group does not have a `source` value of `custom`.
|
|
"404":
|
|
description: Can't find the group.
|
|
"200":
|
|
description: Successfully added the group members.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GroupMember"
|
|
"/v1/team/groups/{group_id}/stats":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get group stats
|
|
description: |
|
|
Retrieve the stats of a given group.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.26
|
|
operationId: GetGroupStats
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: Group GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Group stats retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
group_id:
|
|
type: string
|
|
total_member_count:
|
|
type: integer
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/channels/{channel_id}/groups":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get channel groups
|
|
description: |
|
|
Retrieve the list of groups associated with a given channel.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupsByChannel
|
|
parameters:
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of groups per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: filter_allow_reference
|
|
in: query
|
|
description: Boolean which filters the group entries with the `allow_reference` attribute set.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/teams/{team_id}/groups":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get team groups
|
|
description: |
|
|
Retrieve the list of groups associated with a given team.
|
|
|
|
##### Permissions
|
|
Must have the `list_team_channels` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupsByTeam
|
|
parameters:
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of groups per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: filter_allow_reference
|
|
in: query
|
|
description: Boolean which filters in the group entries with the `allow_reference` attribute set.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: include_member_count
|
|
in: query
|
|
description: Boolean which adds a `member_count` field to each group object.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: include_timezones
|
|
in: query
|
|
description: Boolean which adds timezone information for group members.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: include_total_count
|
|
in: query
|
|
description: Boolean which adds total count of groups in the response.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: include_archived
|
|
in: query
|
|
description: Boolean which includes archived groups in the response.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: filter_archived
|
|
in: query
|
|
description: Boolean which filters out archived groups from the response.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: filter_parent_team_permitted
|
|
in: query
|
|
description: Boolean which filters groups based on parent team permissions.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: filter_has_member
|
|
in: query
|
|
description: User ID to filter groups that have this member.
|
|
schema:
|
|
type: string
|
|
- name: include_member_ids
|
|
in: query
|
|
description: Boolean which adds member IDs to the group objects.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: only_syncable_sources
|
|
in: query
|
|
description: Boolean which includes groups from syncable sources.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/teams/{team_id}/groups_by_channels":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get team groups by channels
|
|
description: |
|
|
Retrieve the set of groups associated with the channels in the given team grouped by channel.
|
|
|
|
##### Permissions
|
|
Must have the `list_team_channels` permission.
|
|
|
|
__Minimum server version__: 5.11
|
|
operationId: GetGroupsAssociatedToChannelsByTeam
|
|
parameters:
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of groups per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: filter_allow_reference
|
|
in: query
|
|
description: Boolean which filters in the group entries with the `allow_reference` attribute set.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: paginate
|
|
in: query
|
|
description: Boolean to determine whether the pagination should be applied or not
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
groups:
|
|
$ref: "#/components/schemas/GroupsAssociatedToChannels"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/users/{user_id}/groups":
|
|
get:
|
|
tags:
|
|
- groups
|
|
summary: Get groups for a userId
|
|
description: |
|
|
Retrieve the list of groups associated to the user
|
|
|
|
__Minimum server version__: 5.24
|
|
operationId: GetGroupsByUserId
|
|
parameters:
|
|
- name: user_id
|
|
in: path
|
|
description: User GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/groups/names":
|
|
post:
|
|
tags:
|
|
- groups
|
|
summary: Get groups by name
|
|
description: |
|
|
Get a list of groups based on a provided list of names.
|
|
|
|
##### Permissions
|
|
Requires an active session but no other permissions.
|
|
|
|
__Minimum server version__: 11.0
|
|
operationId: GetGroupsByNames
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of group names
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Group list retrieval successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|