"/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"