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

api/v4/source/bots.yaml

@@ -0,0 +1,351 @@
+  /api/v4/bots:
+    post:
+      tags:
+        - bots
+      summary: Create a bot
+      description: |
+        Create a new bot account on the system. Username is required.
+        ##### Permissions
+        Must have `create_bot` permission.
+        __Minimum server version__: 5.10
+      operationId: CreateBot
+      requestBody:
+          description: Bot to be created
+          required: true
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - username
+                properties:
+                  username:
+                    type: string
+                  display_name:
+                    type: string
+                  description:
+                    type: string
+      responses:
+        "201":
+          description: Bot creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    get:
+      tags:
+        - bots
+      summary: Get bots
+      description: >
+        Get a page of a list of bots.
+
+        ##### Permissions
+
+        Must have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing.
+
+        __Minimum server version__: 5.10
+      operationId: GetBots
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of users per page.
+          schema:
+            type: integer
+            default: 60
+        - name: include_deleted
+          in: query
+          description: If deleted bots should be returned.
+          schema:
+            type: boolean
+        - name: only_orphaned
+          in: query
+          description: When true, only orphaned bots will be returned. A bot is considered
+            orphaned if its owner has been deactivated.
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Bot page retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/bots/{bot_user_id}":
+    put:
+      tags:
+        - bots
+      summary: Patch a bot
+      description: >
+        Partially update a bot by providing only the fields you want to update.
+        Omitted fields will not be updated. The fields that can be updated are
+        defined in the request body, all other provided fields will be ignored.
+
+        ##### Permissions
+
+        Must have `manage_bots` permission. 
+
+        __Minimum server version__: 5.10
+      operationId: PatchBot
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+      requestBody:
+          description: Bot to be created
+          required: true
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - username
+                properties:
+                  username:
+                    type: string
+                  display_name:
+                    type: string
+                  description:
+                    type: string
+      responses:
+        "200":
+          description: Bot patch successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    get:
+      tags:
+        - bots
+      summary: Get a bot
+      description: >
+        Get a bot specified by its bot id.
+
+        ##### Permissions
+
+        Must have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing.
+
+        __Minimum server version__: 5.10
+      operationId: GetBot
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+        - name: include_deleted
+          in: query
+          description: If deleted bots should be returned.
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Bot successfully retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/bots/{bot_user_id}/disable":
+    post:
+      tags:
+        - bots
+      summary: Disable a bot
+      description: |
+        Disable a bot.
+        ##### Permissions
+        Must have `manage_bots` permission. 
+        __Minimum server version__: 5.10
+      operationId: DisableBot
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Bot successfully disabled.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/bots/{bot_user_id}/enable":
+    post:
+      tags:
+        - bots
+      summary: Enable a bot
+      description: |
+        Enable a bot.
+        ##### Permissions
+        Must have `manage_bots` permission. 
+        __Minimum server version__: 5.10
+      operationId: EnableBot
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Bot successfully enabled.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/bots/{bot_user_id}/assign/{user_id}":
+    post:
+      tags:
+        - bots
+      summary: Assign a bot to a user
+      description: |
+        Assign a bot to a specified user.
+        ##### Permissions
+        Must have `manage_bots` permission. 
+        __Minimum server version__: 5.10
+      operationId: AssignBot
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+        - name: user_id
+          in: path
+          description: The user ID to assign the bot to.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Bot successfully assigned.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Bot"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/bots/{bot_user_id}/convert_to_user":
+    post:
+      tags:
+        - bots
+        - users
+      summary: Convert a bot into a user
+      description: |
+        Convert a bot into a user.
+
+        __Minimum server version__: 5.26
+
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: ConvertBotToUser
+      parameters:
+        - name: bot_user_id
+          in: path
+          description: Bot user ID
+          required: true
+          schema:
+            type: string
+        - name: set_system_admin
+          in: query
+          description: Whether to give the user the system admin role.
+          schema:
+            type: boolean
+            default: false
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                email:
+                  type: string
+                username:
+                  type: string
+                password:
+                  type: string
+                first_name:
+                  type: string
+                last_name:
+                  type: string
+                nickname:
+                  type: string
+                locale:
+                  type: string
+                position:
+                  type: string
+                props:
+                  type: object
+                notify_props:
+                  $ref: "#/components/schemas/UserNotifyProps"
+        description: Data to be used in the user creation
+        required: true
+      responses:
+        "200":
+          description: Bot successfully converted
+          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"