From 55496c07c116f415244b14bbead53bc728f04d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Espino=20Garc=C3=ADa?= Date: Mon, 11 May 2026 12:29:25 +0200 Subject: [PATCH] Update API docs (#36302) * Update API docs * Coderabbit comments * Address feedback * Address feedback * Coderabbit feedback --- api/Makefile | 2 - api/v4/source/ai.yaml | 54 -- api/v4/source/bleve.yaml | 28 - api/v4/source/bots.yaml | 121 ----- api/v4/source/channels.yaml | 124 +++++ api/v4/source/cloud.yaml | 148 ++--- api/v4/source/commands.yaml | 2 +- api/v4/source/definitions.yaml | 217 +++++++- api/v4/source/exports.yaml | 40 ++ api/v4/source/files.yaml | 106 ++++ api/v4/source/groups.yaml | 278 +++++----- api/v4/source/introduction.yaml | 12 +- api/v4/source/jobs.yaml | 84 ++- api/v4/source/outgoing_oauth_connections.yaml | 20 +- api/v4/source/plugins.yaml | 68 ++- api/v4/source/posts.yaml | 110 ++++ api/v4/source/remoteclusters.yaml | 170 +++++- api/v4/source/sharedchannels.yaml | 13 +- api/v4/source/system.yaml | 370 +++++++++++-- api/v4/source/teams.yaml | 8 +- api/v4/source/uploads.yaml | 10 +- api/v4/source/usage.yaml | 29 + api/v4/source/users.yaml | 514 ++++++++++++------ .../cloud/billing/after_subscription_spec.js | 10 +- server/scripts/vet-api-check.sh | 50 +- webapp/platform/client/src/client4.ts | 7 - 26 files changed, 1860 insertions(+), 735 deletions(-) delete mode 100644 api/v4/source/ai.yaml delete mode 100644 api/v4/source/bleve.yaml diff --git a/api/Makefile b/api/Makefile index c54262a3a23..041d7f20cbe 100644 --- a/api/Makefile +++ b/api/Makefile @@ -21,7 +21,6 @@ build-v4: node_modules playbooks @cat $(V4_SRC)/preferences.yaml >> $(V4_YAML) @cat $(V4_SRC)/files.yaml >> $(V4_YAML) @cat $(V4_SRC)/recaps.yaml >> $(V4_YAML) - @cat $(V4_SRC)/ai.yaml >> $(V4_YAML) @cat $(V4_SRC)/uploads.yaml >> $(V4_YAML) @cat $(V4_SRC)/jobs.yaml >> $(V4_YAML) @cat $(V4_SRC)/system.yaml >> $(V4_YAML) @@ -36,7 +35,6 @@ build-v4: node_modules playbooks @cat $(V4_SRC)/commands.yaml >> $(V4_YAML) @cat $(V4_SRC)/oauth.yaml >> $(V4_YAML) @cat $(V4_SRC)/elasticsearch.yaml >> $(V4_YAML) - @cat $(V4_SRC)/bleve.yaml >> $(V4_YAML) @cat $(V4_SRC)/dataretention.yaml >> $(V4_YAML) @cat $(V4_SRC)/plugins.yaml >> $(V4_YAML) @cat $(V4_SRC)/roles.yaml >> $(V4_YAML) diff --git a/api/v4/source/ai.yaml b/api/v4/source/ai.yaml deleted file mode 100644 index 183bcbbf189..00000000000 --- a/api/v4/source/ai.yaml +++ /dev/null @@ -1,54 +0,0 @@ - /api/v4/ai/agents: - get: - tags: - - ai - summary: Get available AI agents - description: > - Retrieve all available AI agents from the AI plugin's bridge API. - If a user ID is provided, only agents accessible to that user are returned. - - ##### Permissions - - Must be authenticated. - - __Minimum server version__: 11.2 - operationId: GetAIAgents - responses: - "200": - description: AI agents retrieved successfully - content: - application/json: - schema: - $ref: "#/components/schemas/AgentsResponse" - "401": - $ref: "#/components/responses/Unauthorized" - "500": - $ref: "#/components/responses/InternalServerError" - /api/v4/ai/services: - get: - tags: - - ai - summary: Get available AI services - description: > - Retrieve all available AI services from the AI plugin's bridge API. - If a user ID is provided, only services accessible to that user - (via their permitted bots) are returned. - - ##### Permissions - - Must be authenticated. - - __Minimum server version__: 11.2 - operationId: GetAIServices - responses: - "200": - description: AI services retrieved successfully - content: - application/json: - schema: - $ref: "#/components/schemas/ServicesResponse" - "401": - $ref: "#/components/responses/Unauthorized" - "500": - $ref: "#/components/responses/InternalServerError" - diff --git a/api/v4/source/bleve.yaml b/api/v4/source/bleve.yaml deleted file mode 100644 index 35ce63b2c91..00000000000 --- a/api/v4/source/bleve.yaml +++ /dev/null @@ -1,28 +0,0 @@ - /api/v4/bleve/purge_indexes: - post: - tags: - - bleve - summary: Purge all Bleve indexes - description: > - Deletes all Bleve indexes and their contents. After calling this - endpoint, it is - - necessary to schedule a new Bleve indexing job to repopulate the indexes. - - __Minimum server version__: 5.24 - - ##### Permissions - - Must have `sysconsole_write_experimental` permission. - operationId: PurgeBleveIndexes - responses: - "200": - description: Indexes purged successfully. - content: - application/json: - schema: - $ref: "#/components/schemas/StatusOK" - "500": - $ref: "#/components/responses/InternalServerError" - "501": - $ref: "#/components/responses/NotImplemented" diff --git a/api/v4/source/bots.yaml b/api/v4/source/bots.yaml index c30ccf8372c..b5334183351 100644 --- a/api/v4/source/bots.yaml +++ b/api/v4/source/bots.yaml @@ -279,127 +279,6 @@ $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" - "/api/v4/bots/{bot_user_id}/icon": - get: - tags: - - bots - summary: Get bot's LHS icon - description: | - Get a bot's LHS icon image based on bot_user_id string parameter. - ##### Permissions - Must be logged in. - __Minimum server version__: 5.14 - operationId: GetBotIconImage - parameters: - - name: bot_user_id - in: path - description: Bot user ID - required: true - schema: - type: string - responses: - "200": - description: Bot's LHS icon image - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "404": - $ref: "#/components/responses/NotFound" - "500": - $ref: "#/components/responses/InternalServerError" - "501": - $ref: "#/components/responses/NotImplemented" - post: - tags: - - bots - summary: Set bot's LHS icon image - description: > - Set a bot's LHS icon image based on bot_user_id string parameter. Icon - image must be SVG format, all other formats are rejected. - - ##### Permissions - - Must have `manage_bots` permission. - - __Minimum server version__: 5.14 - operationId: SetBotIconImage - parameters: - - name: bot_user_id - in: path - description: Bot user ID - required: true - schema: - type: string - requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - image: - description: SVG icon image to be uploaded - type: string - format: binary - required: - - image - responses: - "200": - description: SVG icon image set successful - content: - application/json: - schema: - $ref: "#/components/schemas/StatusOK" - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "413": - $ref: "#/components/responses/TooLarge" - "500": - $ref: "#/components/responses/InternalServerError" - "501": - $ref: "#/components/responses/NotImplemented" - delete: - tags: - - bots - summary: Delete bot's LHS icon image - description: | - Delete bot's LHS icon image based on bot_user_id string parameter. - ##### Permissions - Must have `manage_bots` permission. - __Minimum server version__: 5.14 - operationId: DeleteBotIconImage - parameters: - - name: bot_user_id - in: path - description: Bot user ID - required: true - schema: - type: string - responses: - "200": - description: Icon image deletion successful - content: - application/json: - schema: - $ref: "#/components/schemas/StatusOK" - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "404": - $ref: "#/components/responses/NotFound" - "500": - $ref: "#/components/responses/InternalServerError" - "501": - $ref: "#/components/responses/NotImplemented" "/api/v4/bots/{bot_user_id}/convert_to_user": post: tags: diff --git a/api/v4/source/channels.yaml b/api/v4/source/channels.yaml index 7a3794d8596..9566147659a 100644 --- a/api/v4/source/channels.yaml +++ b/api/v4/source/channels.yaml @@ -1980,6 +1980,83 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + "/api/v4/channels/members/{user_id}/mark_read": + post: + tags: + - channels + summary: Mark multiple channels as read + description: | + Mark multiple channels as viewed for the given user. + ##### Permissions + Must be logged in as the user or have `edit_other_users` permission. + operationId: MarkChannelsReadForUser + parameters: + - in: path + name: user_id + description: User ID to mark channels read for + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + required: true + responses: + "200": + description: Channels marked as read + content: + application/json: + schema: + type: object + properties: + status: + type: string + last_viewed_at_times: + type: object + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "/api/v4/channels/stats/member_count": + post: + tags: + - channels + summary: Get member counts for multiple channels + description: | + Get channel member counts for a list of channel IDs. + ##### Permissions + Must have access to member count for all requested channels. + operationId: GetChannelsMemberCount + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + required: true + responses: + "200": + description: Channel member counts retrieval successful + content: + application/json: + schema: + type: object + additionalProperties: + type: integer + format: int64 + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" "/api/v4/channels/members/{user_id}/view": post: tags: @@ -2916,3 +2993,50 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + "/api/v4/channels/{channel_id}/convert_to_channel": + post: + tags: + - channels + - group message + summary: Convert group message to private channel + description: | + Converts a group message channel into a private channel in the specified team. + ##### Permissions + Must have `create_private_channel` permission in the destination team. + operationId: ConvertGroupMessageToChannel + parameters: + - name: channel_id + in: path + description: Group message channel ID + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - channel_id + - team_id + properties: + channel_id: + type: string + team_id: + type: string + responses: + "200": + description: Conversion successful + content: + application/json: + schema: + $ref: "#/components/schemas/Channel" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" diff --git a/api/v4/source/cloud.yaml b/api/v4/source/cloud.yaml index ef47b59c6f1..490304896d6 100644 --- a/api/v4/source/cloud.yaml +++ b/api/v4/source/cloud.yaml @@ -58,71 +58,6 @@ $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" - /api/v4/cloud/payment: - post: - tags: - - cloud - summary: Create a customer setup payment intent - description: | - Creates a customer setup payment intent for the given Mattermost cloud installation. - - ##### Permissions - - Must have `manage_system` permission and be licensed for Cloud. - - __Minimum server version__: 5.28 - __Note:__: This is intended for internal use and is subject to change. - - operationId: CreateCustomerPayment - responses: - "201": - description: Payment setup intented created - content: - application/json: - schema: - $ref: "#/components/schemas/PaymentSetupIntent" - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "501": - $ref: "#/components/responses/NotImplemented" - /api/v4/cloud/payment/confirm: - post: - tags: - - cloud - summary: Completes the payment setup intent - description: > - Confirms the payment setup intent initiated when posting to `/cloud/payment`. - - ##### Permissions - - Must have `manage_system` permission and be licensed for Cloud. - - __Minimum server version__: 5.28 - __Note:__ This is intended for internal use and is subject to change. - operationId: ConfirmCustomerPayment - requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - stripe_setup_intent_id: - type: string - responses: - "200": - description: Payment setup intent confirmed successfully - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "501": - $ref: "#/components/responses/NotImplemented" /api/v4/cloud/customer: get: tags: @@ -237,6 +172,73 @@ $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" + /api/v4/cloud/validate-business-email: + post: + tags: + - cloud + summary: Validate business email + description: > + Validate whether an email address is considered a business email by the cloud service. + + ##### Permissions + Must be authenticated. + operationId: ValidateBusinessEmail + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - email + properties: + email: + type: string + responses: + "200": + description: Email validation successful + content: + application/json: + schema: + type: object + properties: + is_valid: + type: boolean + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" + /api/v4/cloud/validate-workspace-business-email: + post: + tags: + - cloud + summary: Validate workspace business email + description: > + Validate the current workspace customer/admin email as a business email. + + ##### Permissions + Must have `sysconsole_write_billing` permission and be licensed for Cloud. + operationId: ValidateWorkspaceBusinessEmail + responses: + "200": + description: Workspace email validation successful + content: + application/json: + schema: + type: object + properties: + is_valid: + type: boolean + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" /api/v4/cloud/subscription: get: tags: @@ -360,6 +362,22 @@ $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" + /api/v4/hosted_customer/signup_available: + get: + tags: + - cloud + summary: Check hosted signup availability + description: > + Checks whether hosted signup is available for self-hosted workspaces. + + ##### Permissions + Must be authenticated. + operationId: HostedCustomerSignupAvailable + responses: + "401": + $ref: "#/components/responses/Unauthorized" + "501": + $ref: "#/components/responses/NotImplemented" /api/v4/cloud/check-cws-connection: get: tags: diff --git a/api/v4/source/commands.yaml b/api/v4/source/commands.yaml index c2019d6c8ee..0eb42ea4da4 100644 --- a/api/v4/source/commands.yaml +++ b/api/v4/source/commands.yaml @@ -121,7 +121,7 @@ $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" - '/api/v4/teams/{team_id}/commands/autocomplete_suggestions': + "/api/v4/teams/{team_id}/commands/autocomplete_suggestions": get: tags: - commands diff --git a/api/v4/source/definitions.yaml b/api/v4/source/definitions.yaml index e2abece907c..0968f660efe 100644 --- a/api/v4/source/definitions.yaml +++ b/api/v4/source/definitions.yaml @@ -473,6 +473,200 @@ components: type: string metadata: $ref: "#/components/schemas/PostMetadata" + PostPriority: + type: object + description: Priority metadata associated with a post or draft. + properties: + priority: + type: string + description: The priority label of a post, either empty, important, or urgent. + enum: + - "" + - important + - urgent + requested_ack: + type: boolean + description: Whether the post author has requested acknowledgements. + persistent_notifications: + type: boolean + description: Whether persistent notifications are enabled for the post. + PostInfo: + type: object + description: Additional team and channel context metadata for a post. + properties: + channel_id: + type: string + description: The ID of the channel containing the post. + channel_type: + type: string + description: The type of the channel containing the post. + channel_display_name: + type: string + description: The display name of the channel containing the post. + has_joined_channel: + type: boolean + description: Whether the requesting user is already a member of the channel. + team_id: + type: string + description: The ID of the team containing the channel, if applicable. + team_type: + type: string + description: The type of the team containing the channel, if applicable. + team_display_name: + type: string + description: The display name of the team containing the channel, if applicable. + has_joined_team: + type: boolean + description: Whether the requesting user is already a member of the team. + Draft: + type: object + properties: + create_at: + type: integer + format: int64 + update_at: + type: integer + format: int64 + delete_at: + type: integer + format: int64 + description: Deprecated. Drafts are hard-deleted. + user_id: + type: string + channel_id: + type: string + root_id: + type: string + message: + type: string + type: + type: string + props: + type: object + additionalProperties: true + file_ids: + type: array + items: + type: string + metadata: + $ref: "#/components/schemas/PostMetadata" + priority: + $ref: "#/components/schemas/PostPriority" + DraftUpsertRequest: + type: object + required: + - channel_id + - message + properties: + channel_id: + type: string + root_id: + type: string + message: + type: string + description: Draft message. Set to an empty string to delete the draft. + type: + type: string + props: + type: object + additionalProperties: true + file_ids: + type: array + items: + type: string + priority: + $ref: "#/components/schemas/PostPriority" + NotifyAdminToUpgradeRequest: + type: object + properties: + trial_notification: + type: boolean + required_plan: + type: string + required_feature: + type: string + PluginReattachAddress: + type: object + properties: + Name: + type: string + Net: + type: string + PluginReattachConfig: + type: object + properties: + Protocol: + type: string + ProtocolVersion: + type: integer + Addr: + $ref: "#/components/schemas/PluginReattachAddress" + Pid: + type: integer + Test: + type: boolean + PluginReattachRequest: + type: object + required: + - Manifest + - PluginReattachConfig + properties: + Manifest: + $ref: "#/components/schemas/PluginManifest" + PluginReattachConfig: + $ref: "#/components/schemas/PluginReattachConfig" + InstallMarketplacePluginRequest: + type: object + required: + - id + properties: + id: + type: string + description: The ID of the plugin to install. + version: + type: string + description: Optional plugin version. If omitted, the latest compatible version is installed. + RemoteClusterMsg: + type: object + properties: + id: + type: string + topic: + type: string + create_at: + type: integer + format: int64 + payload: + description: Raw message payload. + type: object + additionalProperties: true + RemoteClusterFrame: + type: object + properties: + remote_id: + type: string + msg: + $ref: "#/components/schemas/RemoteClusterMsg" + RemoteClusterPing: + type: object + properties: + sent_at: + type: integer + format: int64 + recv_at: + type: integer + format: int64 + RemoteClusterResponse: + type: object + properties: + status: + type: string + err: + type: string + payload: + description: Raw response payload. + type: object + additionalProperties: true PropertyField: type: object properties: @@ -716,17 +910,11 @@ components: items: $ref: "#/components/schemas/Reaction" priority: - type: object + allOf: + - $ref: "#/components/schemas/PostPriority" description: > Post priority set for this post. This field will be null if no priority metadata has been set. - properties: - priority: - type: string - description: The priority label of a post, could be either empty, important, or urgent. - requested_ack: - type: boolean - description: Whether the post author has requested for acknowledgements or not. acknowledgements: type: array description: > @@ -3340,13 +3528,6 @@ components: active: type: integer nullable: true - PaymentSetupIntent: - type: object - properties: - id: - type: string - client_secret: - type: string PaymentMethod: type: object properties: @@ -4093,12 +4274,6 @@ components: type: array items: $ref: "#/components/schemas/UserThread" - LicenseRenewalLink: - type: object - properties: - renewal_link: - description: License renewal link - type: string System: type: object properties: diff --git a/api/v4/source/exports.yaml b/api/v4/source/exports.yaml index badbe391705..4dbf619892a 100644 --- a/api/v4/source/exports.yaml +++ b/api/v4/source/exports.yaml @@ -84,3 +84,43 @@ $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" + "/api/v4/exports/{export_name}/presign-url": + post: + tags: + - exports + summary: Create a presigned URL for export download + description: | + Creates a presigned URL for downloading an export file. + + __Minimum server version__: 5.33 + + ##### Permissions + Must have `manage_system` permission. + operationId: PresignExport + parameters: + - name: export_name + in: path + description: The name of the export file + required: true + schema: + type: string + responses: + "200": + description: Presigned URL created successfully + content: + application/json: + schema: + type: object + properties: + url: + type: string + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" diff --git a/api/v4/source/files.yaml b/api/v4/source/files.yaml index e116ae0a197..b8c37223166 100644 --- a/api/v4/source/files.yaml +++ b/api/v4/source/files.yaml @@ -126,6 +126,31 @@ $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" + head: + tags: + - files + summary: Get file metadata headers + description: | + Performs the same permission and existence checks as getting a file, but returns headers only. + operationId: HeadFile + parameters: + - name: file_id + in: path + description: The ID of the file to get + required: true + schema: + type: string + responses: + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "501": + $ref: "#/components/responses/NotImplemented" "/api/v4/files/{file_id}/thumbnail": get: tags: @@ -163,6 +188,31 @@ $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" + head: + tags: + - files + summary: Get thumbnail metadata headers + description: | + Performs the same permission and existence checks as getting a thumbnail, but returns headers only. + operationId: HeadFileThumbnail + parameters: + - name: file_id + in: path + description: The ID of the file to get + required: true + schema: + type: string + responses: + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "501": + $ref: "#/components/responses/NotImplemented" "/api/v4/files/{file_id}/preview": get: tags: @@ -200,6 +250,31 @@ $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" + head: + tags: + - files + summary: Get preview metadata headers + description: | + Performs the same permission and existence checks as getting a preview, but returns headers only. + operationId: HeadFilePreview + parameters: + - name: file_id + in: path + description: The ID of the file to get + required: true + schema: + type: string + responses: + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "501": + $ref: "#/components/responses/NotImplemented" "/api/v4/files/{file_id}/link": get: tags: @@ -334,6 +409,37 @@ $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" + head: + tags: + - files + summary: Get public file metadata headers + description: | + Performs the same validation checks as getting a public file, but returns headers only. + operationId: HeadFilePublic + parameters: + - name: file_id + in: path + description: The ID of the file to get + required: true + schema: + type: string + - name: h + in: query + description: File hash + required: true + schema: + type: string + responses: + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "501": + $ref: "#/components/responses/NotImplemented" "/api/v4/teams/{team_id}/files/search": post: diff --git a/api/v4/source/groups.yaml b/api/v4/source/groups.yaml index aab9b25c6b3..eba8e32b3a6 100644 --- a/api/v4/source/groups.yaml +++ b/api/v4/source/groups.yaml @@ -307,9 +307,11 @@ - groups summary: Link a team to a group description: | - Link a team to a group + Link a team to a group. + ##### Permissions - Must have `manage_team` permission. + 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 @@ -322,13 +324,13 @@ type: string - name: team_id in: path - description: Team GUID + description: Team GUID. required: true schema: type: string responses: "201": - description: Team successfully linked to group + description: Team linked to group content: application/json: schema: @@ -344,11 +346,13 @@ delete: tags: - groups - summary: Delete a link from a team to a group + summary: Unlink a team from a group description: | - Delete a link from a team to a group + Delete a link between a team and a group. + ##### Permissions - Must have `manage_team` permission. + 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 @@ -361,13 +365,13 @@ type: string - name: team_id in: path - description: Team GUID + description: Team GUID. required: true schema: type: string responses: "200": - description: Successfully deleted link between team and group + description: Team unlinked from group content: application/json: schema: @@ -385,15 +389,15 @@ tags: - groups summary: Link a channel to a group - description: > - Link a channel to a group + description: | + Link a channel to a group. ##### Permissions - - If the channel is private, you must have `manage_private_channel_members` permission. - - Otherwise, you must have the `manage_public_channel_members` permission. - + 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 @@ -406,13 +410,13 @@ type: string - name: channel_id in: path - description: Channel GUID + description: Channel GUID. required: true schema: type: string responses: "201": - description: Channel successfully linked to group + description: Channel linked to group content: application/json: schema: @@ -428,16 +432,16 @@ delete: tags: - groups - summary: Delete a link from a channel to a group - description: > - Delete a link from a channel to a group + summary: Unlink a channel from a group + description: | + Delete a link between a channel and a group. ##### Permissions - - If the channel is private, you must have `manage_private_channel_members` permission. - - Otherwise, you must have the `manage_public_channel_members` permission. - + 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 @@ -450,13 +454,13 @@ type: string - name: channel_id in: path - description: Channel GUID + description: Channel GUID. required: true schema: type: string responses: "200": - description: Successfully deleted link between channel and group + description: Channel unlinked from group content: application/json: schema: @@ -473,9 +477,10 @@ get: tags: - groups - summary: Get GroupSyncable from Team ID + summary: Get a team syncable for a group description: | - Get the GroupSyncable object with group_id and team_id from params + Get the GroupSyncableTeam object with the provided group and team identifiers. + ##### Permissions Must have `manage_system` permission. @@ -490,13 +495,13 @@ type: string - name: team_id in: path - description: Team GUID + description: Team GUID. required: true schema: type: string responses: "200": - description: GroupSyncable object retrieval successful + description: Team syncable retrieved content: application/json: schema: @@ -515,9 +520,10 @@ get: tags: - groups - summary: Get GroupSyncable from channel ID + summary: Get a channel syncable for a group description: | - Get the GroupSyncable object with group_id and channel_id from params + Get the GroupSyncableChannel object with the provided group and channel identifiers. + ##### Permissions Must have `manage_system` permission. @@ -532,13 +538,13 @@ type: string - name: channel_id in: path - description: Channel GUID + description: Channel GUID. required: true schema: type: string responses: "200": - description: GroupSyncable object retrieval successful + description: Channel syncable retrieved content: application/json: schema: @@ -557,9 +563,10 @@ get: tags: - groups - summary: Get group teams + summary: Get team syncables for a group description: | - Retrieve the list of teams associated to the group + Retrieve the list of team syncables associated with the group. + ##### Permissions Must have `manage_system` permission. @@ -574,7 +581,7 @@ type: string responses: "200": - description: Teams list retrieval successful + description: Team syncables retrieved content: application/json: schema: @@ -595,9 +602,10 @@ get: tags: - groups - summary: Get group channels + summary: Get channel syncables for a group description: | - Retrieve the list of channels associated to the group + Retrieve the list of channel syncables associated with the group. + ##### Permissions Must have `manage_system` permission. @@ -612,7 +620,7 @@ type: string responses: "200": - description: Channel list retrieval successful + description: Channel syncables retrieved content: application/json: schema: @@ -633,19 +641,14 @@ put: tags: - groups - summary: Patch a GroupSyncable associated to Team + summary: Patch a team syncable for a group description: > - Partially update a GroupSyncable 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. - + 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: @@ -657,24 +660,23 @@ type: string - name: team_id in: path - description: Team GUID + description: Team GUID. required: true schema: type: string requestBody: - description: GroupSyncable object that is to be updated - required: true - content: - application/json: - schema: - type: object - properties: - auto_add: - type: boolean - + description: GroupSyncableTeam object that is to be updated + required: true + content: + application/json: + schema: + type: object + properties: + auto_add: + type: boolean responses: "200": - description: GroupSyncable patch successful + description: Team syncable patched content: application/json: schema: @@ -691,19 +693,14 @@ put: tags: - groups - summary: Patch a GroupSyncable associated to Channel + summary: Patch a channel syncable for a group description: > - Partially update a GroupSyncable 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. - + 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: @@ -715,23 +712,23 @@ type: string - name: channel_id in: path - description: Channel GUID + description: Channel GUID. required: true schema: type: string requestBody: - description: GroupSyncable object that is to be updated - required: true - content: - application/json: - schema: - type: object - properties: - auto_add: - type: boolean + description: GroupSyncableChannel object that is to be updated + required: true + content: + application/json: + schema: + type: object + properties: + auto_add: + type: boolean responses: "200": - description: GroupSyncable patch successful + description: Channel syncable patched content: application/json: schema: @@ -1102,68 +1099,69 @@ "501": $ref: "#/components/responses/NotImplemented" "/api/v4/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. + 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. + ##### 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 - items: + __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" + "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" "/api/v4/users/{user_id}/groups": get: tags: diff --git a/api/v4/source/introduction.yaml b/api/v4/source/introduction.yaml index 2efde426c6c..313b775c802 100644 --- a/api/v4/source/introduction.yaml +++ b/api/v4/source/introduction.yaml @@ -30,9 +30,9 @@ info: * [Authentication](#/#authentication-1) - * [Websocket Events](#/#websocket-events) + * [WebSocket Events](#/#websocket-events) - * [Websocket API](#/#websocket-api) + * [WebSocket API](#/#websocket-api) ### Drivers @@ -110,7 +110,7 @@ info: ```bash curl -i -H 'Authorization: Bearer ckh3t4knu3fzujt76o57f5jo4w' http://localhost:8065/api/v4/users/me ``` - Alternatively, include the `Token` as your `MMAUTHTOKEN` cookie value on you future API requests: + Alternatively, include the `Token` as your `MMAUTHTOKEN` cookie value on your future API requests: ```bash curl -i -H 'Cookie: MMAUTHTOKEN=ckh3t4knu3fzujt76o57f5jo4w' http://localhost:8065/api/v4/users/me @@ -213,7 +213,7 @@ info: Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection. - ### Websocket Events + ### WebSocket Events WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel. @@ -289,7 +289,7 @@ info: - property_field_deleted - property_values_updated - ### Websocket API + ### WebSocket API Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection: @@ -436,7 +436,7 @@ tags: - name: LDAP description: Endpoints for configuring and interacting with LDAP. - name: groups - description: Endpoints related to LDAP groups. + description: Endpoints related to groups, including LDAP-synced and custom groups. - name: compliance description: Endpoints for creating, getting and downloading compliance reports. - name: cluster diff --git a/api/v4/source/jobs.yaml b/api/v4/source/jobs.yaml index 208dd93e7ac..e52020a3991 100644 --- a/api/v4/source/jobs.yaml +++ b/api/v4/source/jobs.yaml @@ -3,15 +3,27 @@ tags: - jobs summary: Get the jobs. - description: > + description: | Get a page of jobs. Use the query parameters to modify the behaviour of this endpoint. __Minimum server version: 4.1__ ##### Permissions + Must have permission to read at least one job type returned by this call. + When no `job_type` query parameter is set, the server only includes job types your session may read; required permission depends on the job type: - Must have `manage_jobs` permission. + - `read_data_retention_job` — `data_retention` + - `read_compliance_export_job` — `message_export` + - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `read_ldap_sync_job` — `ldap_sync` + - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content` + - `manage_system` — `access_control_sync` + + When `job_type` is set, you must have the permission that matches that type (same mapping as above). + + This endpoint does not accept `team_id`. To list `access_control_sync` jobs scoped to a team without `manage_system`, use `GET /api/v4/jobs/type/access_control_sync` with query parameter `team_id` set to the team GUID (requires `manage_team_access_rules` on that team). operationId: GetJobs parameters: - name: page @@ -59,7 +71,15 @@ Create a new job. __Minimum server version: 4.1__ ##### Permissions - Must have `manage_jobs` permission. + Must have permission to create the requested job type. Required permission depends on `type`: + + - `create_data_retention_job` — `data_retention` + - `create_compliance_export_job` — `message_export` + - `create_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `create_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `create_ldap_sync_job` — `ldap_sync` + - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content` + - `access_control_sync` — `manage_system`, or `manage_channel_access_rules` on the channel given in job `data`, or `manage_team_access_rules` on the team in job `data` (see server logic for scoped sync jobs) operationId: CreateJob requestBody: content: @@ -100,7 +120,15 @@ Gets a single job. __Minimum server version: 4.1__ ##### Permissions - Must have `manage_jobs` permission. + Must have permission to read the job's type: + + - `read_data_retention_job` — `data_retention` + - `read_compliance_export_job` — `message_export` + - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `read_ldap_sync_job` — `ldap_sync` + - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content` + - `manage_system` — `access_control_sync` operationId: GetJob parameters: - name: job_id @@ -133,7 +161,7 @@ Download the result of a single job. __Minimum server version: 5.28__ ##### Permissions - Must have `manage_jobs` permission. + Must have `download_compliance_export_result` permission for message export jobs. operationId: DownloadJob parameters: - name: job_id @@ -160,7 +188,15 @@ Cancel a job. __Minimum server version: 4.1__ ##### Permissions - Must have `manage_jobs` permission. + Same as creating that job type (cancel uses the create permission check): + + - `create_data_retention_job` — `data_retention` + - `create_compliance_export_job` — `message_export` + - `create_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `create_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `create_ldap_sync_job` — `ldap_sync` + - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content` + - `access_control_sync` — `manage_system`, or `manage_channel_access_rules` / `manage_team_access_rules` for scoped jobs as when creating operationId: CancelJob parameters: - name: job_id @@ -184,28 +220,43 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - "/api/v4/jobs/type/{type}": + "/api/v4/jobs/type/{job_type}": get: tags: - jobs summary: Get the jobs of the given type. - description: > + description: | Get a page of jobs of the given type. Use the query parameters to modify the behaviour of this endpoint. __Minimum server version: 4.1__ ##### Permissions + Must have permission to read the path `job_type`, using the same mapping as `GET /api/v4/jobs`: - Must have `manage_jobs` permission. + - `read_data_retention_job` — `data_retention` + - `read_compliance_export_job` — `message_export` + - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `read_ldap_sync_job` — `ldap_sync` + - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content` + - `manage_system` — `access_control_sync` + + When `job_type` is `access_control_sync` and query parameter `team_id` is set to a valid team GUID, team admins with `manage_team_access_rules` on that team may list jobs scoped to that team without `manage_system`. When `team_id` is set, results include only jobs whose stored data matches that team for the requested type. operationId: GetJobsByType parameters: - - name: type + - name: job_type in: path description: Job type required: true schema: type: string + - name: team_id + in: query + description: | + Optional team GUID. When set, the server returns jobs of the given `job_type` whose job data includes this `team_id` (see server filtering). For `access_control_sync`, team admins with `manage_team_access_rules` on this team may use this parameter to read team-scoped jobs without `manage_system`. + schema: + type: string - name: page in: query description: The page to select. @@ -238,13 +289,24 @@ tags: - jobs summary: Update the status of a job - description: > + description: | Update the status of a job. Valid status updates: - 'in_progress' -> 'pending' - 'in_progress' | 'pending' -> 'cancel_requested' - 'cancel_requested' -> 'canceled' Add force to the body of the PATCH request to bypass the given rules, the only statuses you can go to are: pending, cancel_requested and canceled. This can have unexpected consequences and should be used with caution. + + ##### Permissions + Must have permission to manage the job's type: + + - `manage_data_retention_job` — `data_retention` + - `manage_compliance_export_job` — `message_export` + - `manage_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing` + - `manage_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation` + - `manage_ldap_sync_job` — `ldap_sync` + - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content` + - `manage_system` — `access_control_sync` operationId: UpdateJobStatus parameters: - name: job_id diff --git a/api/v4/source/outgoing_oauth_connections.yaml b/api/v4/source/outgoing_oauth_connections.yaml index 1006fa433e5..ba04cd1b31b 100644 --- a/api/v4/source/outgoing_oauth_connections.yaml +++ b/api/v4/source/outgoing_oauth_connections.yaml @@ -71,7 +71,7 @@ $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/NotImplemented" - /api/v4/oauth/outgoing_connections/{connection_id}: + /api/v4/oauth/outgoing_connections/{outgoing_oauth_connection_id}: get: tags: - oauth @@ -84,6 +84,12 @@ __Minimum server version__: 9.6 operationId: GetOutgoingOAuthConnection parameters: + - name: outgoing_oauth_connection_id + in: path + description: Outgoing OAuth connection ID + required: true + schema: + type: string - name: team_id in: query description: Current Team ID in integrations backstage @@ -115,6 +121,12 @@ __Minimum server version__: 9.6 operationId: UpdateOutgoingOAuthConnection parameters: + - name: outgoing_oauth_connection_id + in: path + description: Outgoing OAuth connection ID + required: true + schema: + type: string - name: team_id in: query description: Current Team ID in integrations backstage @@ -156,6 +168,12 @@ __Minimum server version__: 9.6 operationId: DeleteOutgoingOAuthConnection parameters: + - name: outgoing_oauth_connection_id + in: path + description: Outgoing OAuth connection ID + required: true + schema: + type: string - name: team_id in: query description: Current Team ID in integrations backstage diff --git a/api/v4/source/plugins.yaml b/api/v4/source/plugins.yaml index 60068c3dc74..23179d5eb58 100644 --- a/api/v4/source/plugins.yaml +++ b/api/v4/source/plugins.yaml @@ -333,17 +333,7 @@ content: application/json: schema: - type: object - required: - - id - - version - properties: - id: - type: string - description: The ID of the plugin to install. - version: - type: string - description: The version of the plugin to install. + $ref: "#/components/schemas/InstallMarketplacePluginRequest" description: The metadata identifying the plugin to install. required: true responses: @@ -477,3 +467,59 @@ $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" + + /api/v4/plugins/reattach: + post: + tags: + - plugins + summary: Reattach a plugin process + description: | + Reattaches the server to an already running plugin process. + This endpoint is only exposed over a local socket. + + ##### Permissions + Must have `manage_system` permission. + operationId: ReattachPlugin + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PluginReattachRequest" + responses: + "200": + description: Plugin reattached successfully + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + + "/api/v4/plugins/{plugin_id}/detach": + post: + tags: + - plugins + summary: Detach a reattached plugin process + description: | + Detaches a previously reattached plugin from the server. + This endpoint is only exposed over a local socket. + + ##### Permissions + Must have `manage_system` permission. + operationId: DetachPlugin + parameters: + - name: plugin_id + in: path + description: The ID of the plugin to detach. + required: true + schema: + type: string + responses: + "200": + description: Plugin detached successfully + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" diff --git a/api/v4/source/posts.yaml b/api/v4/source/posts.yaml index c390b71eb50..9cdae53d8da 100644 --- a/api/v4/source/posts.yaml +++ b/api/v4/source/posts.yaml @@ -127,6 +127,50 @@ $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" + /api/v4/posts/search: + post: + tags: + - posts + summary: Search posts across all teams + description: | + Search posts visible to the current user across all teams. + ##### Permissions + Must be authenticated. + operationId: SearchPostsInAllTeams + requestBody: + content: + application/json: + schema: + type: object + required: + - terms + properties: + terms: + type: string + is_or_search: + type: boolean + time_zone_offset: + type: integer + include_deleted_channels: + type: boolean + page: + type: integer + per_page: + type: integer + required: true + responses: + "200": + description: Post search successful + content: + application/json: + schema: + $ref: "#/components/schemas/PostListWithSearchMatches" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" "/api/v4/posts/{post_id}": get: tags: @@ -550,6 +594,72 @@ $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" + "/api/v4/posts/{post_id}/info": + get: + tags: + - posts + summary: Get post info + description: | + Get additional metadata and access information for a post. + ##### Permissions + Must be able to access the post's team and channel context. + operationId: GetPostInfo + parameters: + - name: post_id + in: path + description: Post ID + required: true + schema: + type: string + responses: + "200": + description: Post info retrieval successful + content: + application/json: + schema: + $ref: "#/components/schemas/PostInfo" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "/api/v4/posts/{post_id}/edit_history": + get: + tags: + - posts + summary: Get post edit history + description: | + Get edit history entries for a post. + ##### Permissions + Must have `edit_post` permission in the channel. For most posts, only the original author can access history. + operationId: GetEditHistoryForPost + parameters: + - name: post_id + in: path + description: Post ID + required: true + schema: + type: string + responses: + "200": + description: Edit history retrieval successful + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Post" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/posts": get: tags: diff --git a/api/v4/source/remoteclusters.yaml b/api/v4/source/remoteclusters.yaml index 5e981f2cfd1..f347f4b8d04 100644 --- a/api/v4/source/remoteclusters.yaml +++ b/api/v4/source/remoteclusters.yaml @@ -297,9 +297,177 @@ content: application/json: schema: - type: object $ref: "#/components/schemas/RemoteCluster" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" + + "/api/v4/remotecluster/ping": + post: + tags: + - remote clusters + summary: Receive a ping from a remote cluster. + description: | + Receives heartbeat traffic from an already linked remote cluster. + This endpoint is authenticated with a remote-cluster token and is + used by the secure connection transport layer. + + ##### Permissions + No user session permissions required. + operationId: RemoteClusterPing + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RemoteClusterFrame" + responses: + "200": + description: Ping response successful + content: + application/json: + schema: + $ref: "#/components/schemas/RemoteClusterPing" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + + "/api/v4/remotecluster/msg": + post: + tags: + - remote clusters + summary: Receive a remote cluster message. + description: | + Receives and processes an incoming transport message from a linked + remote cluster. This endpoint is authenticated with a remote-cluster + token and is part of the secure connection protocol. + + ##### Permissions + No user session permissions required. + operationId: RemoteClusterAcceptMessage + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RemoteClusterFrame" + responses: + "200": + description: Message accepted successfully + content: + application/json: + schema: + $ref: "#/components/schemas/RemoteClusterResponse" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + + "/api/v4/remotecluster/confirm_invite": + post: + tags: + - remote clusters + summary: Confirm an invite with a remote cluster. + description: | + Confirms an invitation handshake from a linked remote cluster. + This endpoint is authenticated with a remote-cluster token and is + used by the secure connection protocol. + + ##### Permissions + No user session permissions required. + operationId: RemoteClusterConfirmInvite + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RemoteClusterFrame" + responses: + "200": + description: Invitation confirmation successful + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + + "/api/v4/remotecluster/upload/{upload_id}": + post: + tags: + - remote clusters + summary: Upload file data for a remote upload session. + description: | + Streams file data into an existing upload session from a linked + remote cluster. This endpoint is authenticated with a remote-cluster token. + + ##### Permissions + No user session permissions required. + operationId: UploadRemoteClusterData + parameters: + - name: upload_id + in: path + description: The upload session ID. + required: true + schema: + type: string + requestBody: + content: + application/octet-stream: + schema: + type: string + format: binary + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + responses: + "200": + description: Upload chunk accepted + content: + application/json: + schema: + $ref: "#/components/schemas/FileInfo" + "204": + description: Upload data accepted with no file completion yet + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + + "/api/v4/remotecluster/{user_id}/image": + post: + tags: + - remote clusters + summary: Set profile image for a remote user. + description: | + Uploads and sets a profile image for a remote user managed by the + requesting remote cluster. This endpoint is authenticated with a + remote-cluster token. + + ##### Permissions + No user session permissions required. + operationId: RemoteSetProfileImage + parameters: + - name: user_id + in: path + description: The remote user ID. + required: true + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + image: + type: string + format: binary + responses: + "200": + description: Profile image updated successfully + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" diff --git a/api/v4/source/sharedchannels.yaml b/api/v4/source/sharedchannels.yaml index 346a3ded016..43a8e589c42 100644 --- a/api/v4/source/sharedchannels.yaml +++ b/api/v4/source/sharedchannels.yaml @@ -9,7 +9,9 @@ __Minimum server version__: 5.50 ##### Permissions - Must be authenticated. + Must be authenticated and have the `view_team` permission for the team. + Results are restricted to channels the user is a member of unless the user has + `manage_shared_channels`. operationId: GetAllSharedChannels parameters: - name: team_id @@ -228,6 +230,8 @@ application/json: schema: $ref: "#/components/schemas/StatusOK" + "204": + description: Channel was not shared with the remote cluster. No action needed. "401": $ref: "#/components/responses/Unauthorized" "403": @@ -277,13 +281,14 @@ - shared channels summary: Check if user can DM another user in shared channels context description: | - Checks if a user can send direct messages to another user, considering shared channel restrictions. - This is specifically for shared channels where DMs require direct connections between clusters. + Checks if a user can send direct messages to another user in a shared channels context. + In addition to user visibility, this evaluates remote-cluster direct-connect restrictions + for remote users. __Minimum server version__: 10.11 ##### Permissions - Must be authenticated and have permission to view the user. + Must be authenticated and able to view the target user. operationId: CanUserDirectMessage parameters: - name: user_id diff --git a/api/v4/source/system.yaml b/api/v4/source/system.yaml index 6ca163fb9c7..780ed1c1aa2 100644 --- a/api/v4/source/system.yaml +++ b/api/v4/source/system.yaml @@ -102,13 +102,105 @@ $ref: "#/components/schemas/SystemStatusResponse" "500": $ref: "#/components/responses/InternalServerError" - "/api/v4/system/notices/{teamId}": + /api/v4/websocket: + get: + tags: + - system + summary: Open a WebSocket connection + description: | + Upgrades the HTTP connection to a WebSocket connection used for real-time events and websocket actions. + + ##### Permissions + No permission required to connect. Authentication can be performed via standard API auth (cookie/header) + or by sending an `authentication_challenge` action after connecting. + operationId: ConnectWebSocket + security: [] + parameters: + - name: connection_id + in: query + description: Existing connection identifier for reconnect flows. + required: false + schema: + type: string + - name: sequence_number + in: query + description: Last received sequence number for reconnect flows. + required: false + schema: + type: string + - name: posted_ack + in: query + description: Whether post acknowledgement events are enabled for this connection. + required: false + schema: + type: boolean + - name: disconnect_err_code + in: query + description: Optional close code used by clients to indicate disconnect reason. + required: false + schema: + type: string + responses: + "101": + description: Switching Protocols + "400": + $ref: "#/components/responses/BadRequest" + + /manualtest: + get: + tags: + - system + summary: Run manual testing helpers + description: | + Invokes manual test helpers used by developers and automated manual test scenarios. + This endpoint is only registered when `ServiceSettings.EnableTesting` is enabled. + + ##### Permissions + + None. Authentication is not required; this route uses the same handler stack as other unauthenticated API handlers (`APIHandler`). + + __Security note:__ Only enable `EnableTesting` on non-production, developer-oriented deployments. + operationId: ManualTest + security: [] + parameters: + - name: test + in: query + description: Name of the manual test to run. + required: true + schema: + type: string + - name: uid + in: query + description: Optional unique value used to randomize generated resources. + required: false + schema: + type: string + - name: username + in: query + description: Optional username used for helper account creation. + required: false + schema: + type: string + - name: teamname + in: query + description: Optional team display name used for helper team creation. + required: false + schema: + type: string + responses: + "307": + description: Manual test setup completed and redirected to the default channel. + "400": + $ref: "#/components/responses/BadRequest" + "500": + $ref: "#/components/responses/InternalServerError" + "/api/v4/system/notices/{team_id}": get: tags: - system summary: Get notices for logged in user in specified team description: > - Will return appropriate product notices for current user in the team specified by teamId parameter. + Will return appropriate product notices for current user in the team specified by team_id parameter. __Minimum server version__: 5.26 @@ -135,7 +227,7 @@ required: true schema: type: string - - name: teamId + - name: team_id in: path description: ID of the team required: true @@ -185,6 +277,68 @@ $ref: "#/components/schemas/StatusOK" "500": $ref: "#/components/responses/InternalServerError" + /api/v4/system/onboarding/complete: + get: + tags: + - system + summary: Get first admin onboarding completion status + description: > + Get whether first admin onboarding is complete. + + ##### Permissions + Must have `manage_system` permission. + operationId: GetOnboardingComplete + responses: + "200": + description: Onboarding completion state retrieval successful + content: + application/json: + schema: + $ref: "#/components/schemas/System" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "500": + $ref: "#/components/responses/InternalServerError" + post: + tags: + - system + summary: Complete first admin onboarding + description: > + Mark first admin onboarding as complete and optionally trigger plugin installation. + + ##### Permissions + Must have `manage_system` permission. + operationId: CompleteOnboarding + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + organization: + type: string + description: Organization name for self-hosted onboarding. + install_plugins: + type: array + description: Marketplace plugin IDs to install as part of onboarding. + items: + type: string + responses: + "200": + description: Onboarding completion successful + content: + application/json: + schema: + $ref: "#/components/schemas/StatusOK" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" /api/v4/system/e2e/ai_bridge: put: tags: @@ -531,6 +685,42 @@ $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" + /api/v4/config/migrate: + post: + tags: + - system + summary: Migrate config storage + description: | + Migrate configuration between storage backends. + This endpoint is only exposed over a local socket. + + ##### Permissions + Must have `manage_system` permission. + operationId: MigrateConfig + requestBody: + content: + application/json: + schema: + type: object + required: + - from + - to + properties: + from: + type: string + description: Source config store name. + to: + type: string + description: Destination config store name. + responses: + "200": + description: Config migration successful + "400": + $ref: "#/components/responses/BadRequest" + "403": + $ref: "#/components/responses/Forbidden" + "500": + $ref: "#/components/responses/InternalServerError" /api/v4/config/client: get: tags: @@ -739,35 +929,6 @@ $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" - /api/v4/license/renewal: - get: - tags: - - system - summary: Request the license renewal link - description: > - Request the renewal link that would be used to start the license renewal process - - __Minimum server version__: 5.32 - - ##### Permissions - - Must have `sysconsole_write_about` permission. - operationId: RequestLicenseRenewalLink - responses: - "200": - description: License renewal link obtained - content: - application/json: - schema: - $ref: "#/components/schemas/LicenseRenewalLink" - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "403": - $ref: "#/components/responses/Forbidden" - "500": - $ref: "#/components/responses/InternalServerError" /api/v4/trial-license: post: tags: @@ -811,13 +972,13 @@ summary: Get last trial license used operationId: GetPrevTrialLicense description: > - Get the last trial license used on the sevrer + Get the last trial license used on the server __Minimum server version__: 5.36 ##### Permissions - Must have `manage_systems` permissions. + Must have `manage_system` permission. responses: "200": description: License fetched successfully. @@ -967,6 +1128,77 @@ type: string "403": $ref: "#/components/responses/Forbidden" + /api/v4/logs/query: + post: + tags: + - system + summary: Query server logs with filters + description: > + Query server logs using filter criteria. + + ##### Permissions + Must have `get_logs` permission. + operationId: QueryLogs + parameters: + - name: page + in: query + description: The page to select. + schema: + type: integer + default: 0 + - name: logs_per_page + in: query + description: The number of logs per page. + schema: + type: string + default: "10000" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + server_names: + type: array + items: + type: string + log_levels: + type: array + items: + type: string + date_from: + type: string + description: > + Inclusive start of the time range. The server parses this using the layout + `YYYY-MM-DD HH:MM:SS.mmm ±HH:MM` (milliseconds optional; timezone offset required), + matching Go reference time `2006-01-02 15:04:05.999 -07:00`. + example: "2024-01-15 14:30:45.123 -05:00" + date_to: + type: string + description: > + Inclusive end of the time range. Same format as `date_from` + (`YYYY-MM-DD HH:MM:SS.mmm ±HH:MM`, e.g. `2006-01-02 15:04:05.999 -07:00`). + example: "2024-01-15 14:30:45.123 -05:00" + responses: + "200": + description: Log query successful + content: + application/json: + schema: + type: object + additionalProperties: + type: array + items: + type: object + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "500": + $ref: "#/components/responses/InternalServerError" /api/v4/analytics/old: get: tags: @@ -1012,6 +1244,76 @@ $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" + /api/v4/latest_version: + get: + tags: + - system + summary: Get latest public server release information + description: > + Retrieves metadata about the latest Mattermost server release from GitHub. + + ##### Permissions + Must have `manage_system` permission. + operationId: GetLatestVersion + responses: + "200": + description: Latest release metadata retrieval successful + content: + application/json: + schema: + type: object + properties: + id: + type: integer + tag_name: + type: string + name: + type: string + created_at: + type: string + published_at: + type: string + body: + type: string + html_url: + type: string + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "500": + $ref: "#/components/responses/InternalServerError" + /api/v4/system/schema/version: + get: + tags: + - system + summary: Get applied database schema migrations + description: > + Returns the list of applied database schema migrations. + + ##### Permissions + Must have at least one sysconsole read permission. + operationId: GetAppliedSchemaMigrations + responses: + "200": + description: Applied schema migrations retrieval successful + content: + application/json: + schema: + type: array + items: + type: object + properties: + version: + type: integer + name: + type: string + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "500": + $ref: "#/components/responses/InternalServerError" /api/v4/server_busy: post: tags: diff --git a/api/v4/source/teams.yaml b/api/v4/source/teams.yaml index 110bfa53ba6..cc8cd78154a 100644 --- a/api/v4/source/teams.yaml +++ b/api/v4/source/teams.yaml @@ -378,7 +378,7 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - "/api/v4/teams/name/{name}": + "/api/v4/teams/name/{team_name}": get: tags: - teams @@ -391,7 +391,7 @@ Must be authenticated, team type is open and have the `view_team` permission. operationId: GetTeamByName parameters: - - name: name + - name: team_name in: path description: Team Name required: true @@ -499,7 +499,7 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - "/api/v4/teams/name/{name}/exists": + "/api/v4/teams/name/{team_name}/exists": get: tags: - teams @@ -510,7 +510,7 @@ Must be authenticated. operationId: TeamExists parameters: - - name: name + - name: team_name in: path description: Team Name required: true diff --git a/api/v4/source/uploads.yaml b/api/v4/source/uploads.yaml index 50d2659aaa7..57685f90ce2 100644 --- a/api/v4/source/uploads.yaml +++ b/api/v4/source/uploads.yaml @@ -105,9 +105,17 @@ type: string requestBody: content: - application/x-www-form-urlencoded: + application/octet-stream: + schema: + type: string + format: binary + multipart/form-data: schema: type: object + properties: + file: + type: string + format: binary responses: "201": description: Upload successful diff --git a/api/v4/source/usage.yaml b/api/v4/source/usage.yaml index 1c63f44413b..cc1fb0ad853 100644 --- a/api/v4/source/usage.yaml +++ b/api/v4/source/usage.yaml @@ -50,3 +50,32 @@ $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" + /api/v4/usage/teams: + get: + tags: + - usage + summary: Get current usage of teams + description: > + Retrieve rounded total number of teams for this instance. + + ##### Permissions + Must be authenticated. + operationId: GetTeamsUsage + responses: + "200": + description: Total number of teams returned successfully + content: + application/json: + schema: + type: object + properties: + active: + type: integer + cloud_archived: + type: integer + teams: + type: integer + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServerError" diff --git a/api/v4/source/users.yaml b/api/v4/source/users.yaml index d63c934ed42..572d834c6fd 100644 --- a/api/v4/source/users.yaml +++ b/api/v4/source/users.yaml @@ -43,6 +43,43 @@ $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" + /api/v4/users/login/desktop_token: + post: + tags: + - users + summary: Login using desktop token + description: > + Login to Mattermost with a short-lived desktop token. + + ##### Permissions + No permission required. + operationId: LoginWithDesktopToken + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - token + properties: + token: + type: string + device_id: + type: string + responses: + "200": + description: Desktop token login successful + content: + application/json: + schema: + $ref: "#/components/schemas/User" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" /api/v4/users/login/cws: post: tags: @@ -294,6 +331,64 @@ $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" + /api/v4/users/notify-admin: + post: + tags: + - users + summary: Save notify-admin intent + description: > + Save a notify-admin request for upgrade or trial flows. + + ##### Permissions + Must be authenticated. + operationId: NotifyAdmin + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotifyAdminToUpgradeRequest" + responses: + "200": + description: Notify-admin request saved + content: + application/json: + schema: + $ref: "#/components/schemas/StatusOK" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + /api/v4/users/trigger-notify-admin-posts: + post: + tags: + - users + summary: Trigger notify-admin posts + description: > + Trigger admin notification posts manually when enabled by configuration. + + ##### Permissions + Must be authenticated and have `manage_system` permission. + operationId: TriggerNotifyAdminPosts + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotifyAdminToUpgradeRequest" + responses: + "200": + description: Notify-admin posts triggered successfully + content: + application/json: + schema: + $ref: "#/components/schemas/StatusOK" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" /api/v4/users: post: @@ -1691,45 +1786,6 @@ $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - /api/v4/users/mfa: - post: - tags: - - users - summary: Check MFA - description: > - Check if a user has multi-factor authentication active on their account - by providing a login id. Used to check whether an MFA code needs to be - provided when logging in. - - ##### Permissions - - No permission required. - operationId: CheckUserMfa - requestBody: - content: - application/json: - schema: - type: object - required: - - login_id - properties: - login_id: - description: The email or username used to login - type: string - required: true - responses: - "200": - description: MFA check successful - content: - application/json: - schema: - type: object - properties: - mfa_required: - description: Value will `true` if MFA is active, `false` otherwise - type: boolean - "400": - $ref: "#/components/responses/BadRequest" "/api/v4/users/{user_id}/password": put: tags: @@ -2969,152 +3025,66 @@ '501': $ref: "#/components/responses/NotImplemented" /api/v4/users/migrate_auth/saml: - post: - tags: - - users - - migrate - - authentication - - SAML - summary: Migrate user accounts authentication type to SAML. - description: > - Migrates accounts from one authentication provider to another. - For example, you can upgrade your authentication provider from email to SAML. + post: + tags: + - users + - migrate + - authentication + - SAML + summary: Migrate user accounts authentication type to SAML. + description: > + Migrates accounts from one authentication provider to another. + For example, you can upgrade your authentication provider from email to SAML. - __Minimum server version__: 5.28 + __Minimum server version__: 5.28 - ##### Permissions + ##### Permissions - Must have `manage_system` permission. + Must have `manage_system` permission. - operationId: MigrateAuthToSaml - requestBody: - content: - application/json: - schema: - type: object - required: - - from - - matches - - auto - properties: - from: - description: The current authentication type for the matched users. - type: string - matches: - description: Users map. - type: object - auto: - type: boolean - responses: - '200': - description: Successfully migrated authentication type to LDAP. - '400': - $ref: "#/components/responses/BadRequest" - '401': - $ref: "#/components/responses/Unauthorized" - '403': - $ref: "#/components/responses/Forbidden" - '501': - $ref: "#/components/responses/NotImplemented" - "/api/v4/users/{user_id}/teams/{team_id}/threads": - get: - tags: - - threads - summary: Get all threads that user is following - description: | - Get all threads that user is following - - __Minimum server version__: 5.29 - - ##### Permissions - Must be logged in as the user or have `edit_other_users` permission. - operationId: GetUserThreads - parameters: - - name: user_id - in: path - description: The ID of the user. This can also be "me" which will point to the current user. - required: true - schema: - type: string - - name: team_id - in: path - description: The ID of the team in which the thread is. - required: true - schema: - type: string - - name: since - in: query - description: Since filters the threads based on their LastUpdateAt timestamp. - required: false - schema: - type: integer - - name: deleted - in: query - description: Deleted will specify that even deleted threads should be returned (For mobile sync). - required: false - schema: - type: boolean - default: false - - name: extended - in: query - description: Extended will enrich the response with participant details. - required: false - schema: - type: boolean - default: false - - name: page - in: query - description: Page specifies which part of the results to return, by per_page. - required: false - schema: - type: integer - default: 0 - - name: per_page - in: query - description: The size of the returned chunk of results. - schema: - type: integer - default: 60 - - name: totalsOnly - in: query - description: Setting this to true will only return the total counts. - required: false - schema: - type: boolean - default: false - - name: threadsOnly - in: query - description: Setting this to true will only return threads. - required: false - schema: - type: boolean - default: false - responses: - "200": - description: User's thread retrieval successful + operationId: MigrateAuthToSaml + requestBody: content: application/json: schema: - $ref: "#/components/schemas/UserThreads" - "400": - $ref: "#/components/responses/BadRequest" - "401": - $ref: "#/components/responses/Unauthorized" - "404": - $ref: "#/components/responses/NotFound" - "/api/v4/users/{user_id}/teams/{team_id}/threads/mention_counts": + type: object + required: + - from + - matches + - auto + properties: + from: + description: The current authentication type for the matched users. + type: string + matches: + description: Users map. + type: object + auto: + type: boolean + responses: + '200': + description: Successfully migrated authentication type to SAML. + '400': + $ref: "#/components/responses/BadRequest" + '401': + $ref: "#/components/responses/Unauthorized" + '403': + $ref: "#/components/responses/Forbidden" + '501': + $ref: "#/components/responses/NotImplemented" + "/api/v4/users/{user_id}/teams/{team_id}/threads": get: tags: - threads - summary: Get all unread mention counts from followed threads, per-channel + summary: Get all threads that user is following description: | - Get all unread mention counts from followed threads + Get all threads that user is following __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. - operationId: GetThreadMentionCountsByChannel + operationId: GetUserThreads parameters: - name: user_id in: path @@ -3128,9 +3098,60 @@ required: true schema: type: string + - name: since + in: query + description: Since filters the threads based on their LastUpdateAt timestamp. + required: false + schema: + type: integer + - name: deleted + in: query + description: Deleted will specify that even deleted threads should be returned (For mobile sync). + required: false + schema: + type: boolean + default: false + - name: extended + in: query + description: Extended will enrich the response with participant details. + required: false + schema: + type: boolean + default: false + - name: page + in: query + description: Page specifies which part of the results to return, by per_page. + required: false + schema: + type: integer + default: 0 + - name: per_page + in: query + description: The size of the returned chunk of results. + schema: + type: integer + default: 60 + - name: totalsOnly + in: query + description: Setting this to true will only return the total counts. + required: false + schema: + type: boolean + default: false + - name: threadsOnly + in: query + description: Setting this to true will only return threads. + required: false + schema: + type: boolean + default: false responses: "200": - description: Get was successful + description: User's thread retrieval successful + content: + application/json: + schema: + $ref: "#/components/schemas/UserThreads" "400": $ref: "#/components/responses/BadRequest" "401": @@ -3390,6 +3411,159 @@ $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" + /api/v4/drafts: + post: + tags: + - users + - drafts + summary: Upsert synced draft + description: | + Create or update a synced draft for the current user. + ##### Permissions + Must be authenticated, have permission to create posts in the channel, and synced drafts must be enabled. + operationId: UpsertDraft + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DraftUpsertRequest" + responses: + "201": + description: Draft upsert successful. Returns `null` when an empty message deletes the draft. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Draft" + nullable: true + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" + "/api/v4/users/{user_id}/teams/{team_id}/drafts": + get: + tags: + - users + - drafts + summary: Get synced drafts for a team + description: | + Get synced drafts for the current user in a team. + ##### Permissions + Must have `view_team` permission for the team and synced drafts must be enabled. + operationId: GetDrafts + parameters: + - name: user_id + in: path + description: User ID + required: true + schema: + type: string + - name: team_id + in: path + description: Team ID + required: true + schema: + type: string + responses: + "200": + description: Drafts retrieval successful + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Draft" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" + "/api/v4/users/{user_id}/channels/{channel_id}/drafts": + delete: + tags: + - users + - drafts + summary: Delete synced draft + description: | + Delete a synced draft for a channel. + ##### Permissions + Must be authenticated as the draft owner and synced drafts must be enabled. + operationId: DeleteDraft + parameters: + - name: user_id + in: path + description: User ID + required: true + schema: + type: string + - name: channel_id + in: path + description: Channel ID + required: true + schema: + type: string + responses: + "200": + description: Draft deletion successful + content: + application/json: + schema: + $ref: "#/components/schemas/StatusOK" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" + "/api/v4/users/{user_id}/channels/{channel_id}/drafts/{thread_id}": + delete: + tags: + - users + - drafts + summary: Delete synced thread draft + description: | + Delete a synced draft for a channel thread. + ##### Permissions + Must be authenticated as the draft owner and synced drafts must be enabled. + operationId: DeleteDraftForThread + parameters: + - name: user_id + in: path + description: User ID + required: true + schema: + type: string + - name: channel_id + in: path + description: Channel ID + required: true + schema: + type: string + - name: thread_id + in: path + description: Root post ID of the thread + required: true + schema: + type: string + responses: + "200": + description: Thread draft deletion successful + content: + application/json: + schema: + $ref: "#/components/schemas/StatusOK" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "501": + $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/data_retention/team_policies": get: tags: diff --git a/e2e-tests/cypress/tests/integration/channels/enterprise/cloud/billing/after_subscription_spec.js b/e2e-tests/cypress/tests/integration/channels/enterprise/cloud/billing/after_subscription_spec.js index bbbe74eab9f..777270b247e 100644 --- a/e2e-tests/cypress/tests/integration/channels/enterprise/cloud/billing/after_subscription_spec.js +++ b/e2e-tests/cypress/tests/integration/channels/enterprise/cloud/billing/after_subscription_spec.js @@ -26,7 +26,7 @@ describe('System Console - after subscription scenarios', () => { // # Click Subscribe Now button cy.contains('span', 'Upgrade Now').parent().click(); - cy.intercept('POST', '/api/v4/cloud/payment/confirm').as('confirm'); + cy.intercept('PUT', '/api/v4/cloud/customer').as('customerUpdate'); cy.intercept('GET', '/api/v4/cloud/subscription').as('subscribe'); @@ -47,7 +47,7 @@ describe('System Console - after subscription scenarios', () => { // # Click Subscribe button cy.get('.RHS').find('button').last().should('be.enabled').click(); - cy.wait(['@confirm', '@subscribe']); + cy.wait(['@customerUpdate', '@subscribe']); // * Check for success message cy.findByText('You are now subscribed to Cloud Professional', {timeout: TIMEOUTS.TEN_SEC}).should('be.visible'); @@ -136,9 +136,7 @@ describe('System Console - after subscription scenarios', () => { cy.wait('@customer'); - cy.intercept('POST', '/api/v4/cloud/payment').as('payment'); - - cy.intercept('POST', '/api/v4/cloud/payment/confirm').as('confirm'); + cy.intercept('PUT', '/api/v4/cloud/customer').as('customerUpdate'); cy.intercept('GET', '/api/v4/cloud/subscription').as('subscribe'); @@ -159,7 +157,7 @@ describe('System Console - after subscription scenarios', () => { // # Click Save Credit Card button cy.get('#saveSetting').should('be.enabled').click(); - cy.wait(['@payment', '@confirm']); + cy.wait('@customerUpdate'); cy.wait('@subscribe'); diff --git a/server/scripts/vet-api-check.sh b/server/scripts/vet-api-check.sh index 7dc1ebc30e5..96b2570edce 100755 --- a/server/scripts/vet-api-check.sh +++ b/server/scripts/vet-api-check.sh @@ -2,59 +2,15 @@ set -euo pipefail IFS=$'\n\t' -# Our API vet checks haven't been running for a long time, and there are lots of undocumented APIs. -# To stem the introduction of new, undocumented APIs while we find time to document the old ones, -# filter out all the "known issues" to support the automated CI check. - API_YAML=$ROOT../api/v4/html/static/mattermost-openapi-v4.yaml OUTPUT=$($GO vet -vettool=$GOBIN/mattermost-govet -openApiSync -openApiSync.spec=$API_YAML ./... 2>&1 || true) -echo "All output, some ignored" -echo "========================" +echo "OpenAPI vet output" +echo "==================" echo "$OUTPUT" OUTPUT_EXCLUDING_IGNORED=$(echo "$OUTPUT" | grep -Fv \ -e 'go: downloading' \ - -e 'github.com/mattermost/mattermost/server/v8/channels/api4' \ - -e 'Cannot find /api/v4/channels/members/{user_id}/mark_read method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/channels/members/{user_id}/mark_read method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/channels/stats/member_count method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/channels/{channel_id}/convert_to_channel method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/client_perf method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/products/selfhosted method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/subscription/self-serve-status method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/request-trial method: PUT in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/validate-business-email method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/validate-workspace-business-email method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/check-cws-connection method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/cloud/delete-workspace method: DELETE in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/drafts method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/{user_id}/teams/{team_id}/drafts method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/{user_id}/channels/{channel_id}/drafts/{thread_id} method: DELETE in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/{user_id}/channels/{channel_id}/drafts method: DELETE in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/exports/{export_name:.+\\.zip}/presign-url method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/signup_available method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/bootstrap method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/customer method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/confirm method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/confirm-expand method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/invoices method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/hosted_customer/invoices/{invoice_id:in_[A-Za-z0-9]+}/pdf method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/license/review method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/license/review/status method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/posts/{post_id}/edit_history method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/posts/{post_id}/info method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/posts/search method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/logs/query method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/latest_version method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/system/onboarding/complete method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/system/onboarding/complete method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/system/schema/version method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/usage/teams method: GET in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/login/desktop_token method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/notify-admin method: POST in OpenAPI 3 spec.' \ - -e 'Cannot find /api/v4/users/trigger-notify-admin-posts method: POST in OpenAPI 3 spec.' \ - -e "Handler /api/v4/cloud/subscription is defined with method PUT, but it's not in the spec" \ 2>&1 || true) if [[ ! -z "${OUTPUT_EXCLUDING_IGNORED// }" ]]; then @@ -63,6 +19,6 @@ if [[ ! -z "${OUTPUT_EXCLUDING_IGNORED// }" ]]; then echo "$OUTPUT_EXCLUDING_IGNORED" exit 1 else - echo "Ignoring above errors." + echo "openApiSync passed." exit 0 fi diff --git a/webapp/platform/client/src/client4.ts b/webapp/platform/client/src/client4.ts index 65aaa8f02a0..0b3a36ae540 100644 --- a/webapp/platform/client/src/client4.ts +++ b/webapp/platform/client/src/client4.ts @@ -3873,13 +3873,6 @@ export default class Client4 { ); }; - purgeBleveIndexes = () => { - return this.doFetch( - `${this.getBaseRoute()}/bleve/purge_indexes`, - {method: 'post'}, - ); - }; - uploadLicense = (fileData: File) => { const formData = new FormData(); formData.append('license', fileData);