snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

api/v4/source/remoteclusters.yaml

@@ -0,0 +1,473 @@
+  "/api/v4/remotecluster":
+    get:
+      tags:
+        - remote clusters
+      summary: Get a list of remote clusters.
+      description: |
+        Get a list of remote clusters.
+
+        ##### Permissions
+        `manage_secure_connections` or `manage_shared_channels`
+      operationId: GetRemoteClusters
+      parameters:
+        - name: page
+          in: query
+          description: The page to select
+          schema:
+            type: integer
+        - name: per_page
+          in: query
+          description: The number of remote clusters per page
+          schema:
+            type: integer
+        - name: exclude_offline
+          in: query
+          description: Exclude offline remote clusters
+          schema:
+            type: boolean
+        - name: in_channel
+          in: query
+          description: Select remote clusters in channel
+          schema:
+            type: string
+        - name: not_in_channel
+          in: query
+          description: Select remote clusters not in this channel
+          schema:
+            type: string
+        - name: only_confirmed
+          in: query
+          description: Select only remote clusters already confirmed
+          schema:
+            type: boolean
+        - name: only_plugins
+          in: query
+          description: Select only remote clusters that belong to a plugin
+          schema:
+            type: boolean
+        - name: exclude_plugins
+          in: query
+          description: Select only remote clusters that don't belong to a plugin
+          schema:
+            type: boolean
+        - name: include_deleted
+          in: query
+          description: Include those remote clusters that have been deleted
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Remote clusters fetch successful. Result might be empty.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RemoteCluster"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+    post:
+      tags:
+        - remote clusters
+      summary: Create a new remote cluster.
+      description: |
+        Create a new remote cluster and generate an invite code.
+
+        ##### Permissions
+        `manage_secure_connections`
+      operationId: CreateRemoteCluster
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - default_team_id
+              properties:
+                name:
+                  type: string
+                display_name:
+                  type: string
+                default_team_id:
+                  type: string
+                password:
+                  type: string
+                  description: |
+                    The password to use in the invite code. If empty,
+                    the server will generate one and it will be part
+                    of the response
+      responses:
+        "201":
+          description: Remote cluster creation successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  remote_cluster:
+                    $ref: "#/components/schemas/RemoteCluster"
+                  invite:
+                    type: string
+                    description: The encrypted invite for the newly created remote cluster
+                  password:
+                    type: string
+                    description: |
+                      The password generated by the server if none was
+                      sent on the create request
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  "/api/v4/remotecluster/{remote_id}":
+    get:
+      tags:
+        - remote clusters
+      summary: Get a remote cluster.
+      description: |
+        Get the Remote Cluster details from the provided id string.
+
+        ##### Permissions
+        `manage_secure_connections` or `manage_shared_channels`
+      operationId: GetRemoteCluster
+      parameters:
+        - name: remote_id
+          in: path
+          description: Remote Cluster GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Remote Cluster retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteCluster"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    patch:
+      tags:
+        - remote clusters
+      summary: Patch a remote cluster.
+      description: |
+        Partially update a Remote Cluster by providing only the fields you want to update. Ommited fields will not be updated.
+
+        ##### Permissions
+        `manage_secure_connections`
+      operationId: PatchRemoteCluster
+      parameters:
+        - name: remote_id
+          in: path
+          description: Remote Cluster GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                display_name:
+                  type: string
+                default_team_id:
+                  type: string
+                  description: The team where channels from invites are created
+      responses:
+        "200":
+          description: Remote Cluster patch successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteCluster"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - remote clusters
+      summary: Delete a remote cluster.
+      description: |
+        Deletes a Remote Cluster.
+
+        ##### Permissions
+        `manage_secure_connections`
+      operationId: DeleteRemoteCluster
+      parameters:
+        - name: remote_id
+          in: path
+          description: Remote Cluster GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Remote Cluster deletion successful
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  "/api/v4/remotecluster/{remote_id}/generate_invite":
+    post:
+      tags:
+        - remote clusters
+      summary: Generate invite code.
+      description: |
+        Generates an invite code for a given remote cluster.
+
+        ##### Permissions
+        `manage_secure_connections`
+      operationId: GenerateRemoteClusterInvite
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - password
+              properties:
+                password:
+                  type: string
+                  description: The password to encrypt the invite code with.
+      responses:
+        "201":
+          description: Invite code generated
+          content:
+            application/json:
+              schema:
+                type: string
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  "/api/v4/remotecluster/accept_invite":
+    post:
+      tags:
+        - remote clusters
+      summary: Accept a remote cluster invite code.
+      description: |
+        Accepts a remote cluster invite code.
+
+        ##### Permissions
+        `manage_secure_connections`
+      operationId: AcceptRemoteClusterInvite
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - invite
+                - name
+                - default_team_id
+                - password
+              properties:
+                invite:
+                  type: string
+                name:
+                  type: string
+                display_name:
+                  type: string
+                default_team_id:
+                  type: string
+                password:
+                  type: string
+                  description: The password to decrypt the invite code.
+      responses:
+        "201":
+          description: Invite successfully accepted
+          content:
+            application/json:
+              schema:
+                $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"