Move API Reference (#23777)

* merge mattermost-api-reference unchanged

* api: update repostiory paths

* api: drop GitPod for api (for now)

* api: improved node_modules target

* api: relocate GitHub actions to root

* Update .github/workflows/api.yml

Co-authored-by: Antonis Stamatiou <stamatiou.antonis@gmail.com>

* fix cache-dependency-path

* adopt node-version-file

* pin versions for uses

* tidy steps/runs

* api/.gitpod.yml: tidy

* api: rm now unused .gitlab-ci.yml

---------

Co-authored-by: Antonis Stamatiou <stamatiou.antonis@gmail.com>

.github/workflows/api.yml

@@ -0,0 +1,35 @@
+name: API
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./api
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+
+    - uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+      with:
+        node-version-file: .nvmrc
+        cache: 'npm'
+        cache-dependency-path: api/package-lock.json
+
+    - name: Run build
+      run: make build
+
+    - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+      with:
+        name: mattermost-api-reference
+        path: api/v4/html

api/.gitignore

@@ -0,0 +1,17 @@
+# Mac OSX
+.DS_Store
+
+# VIM
+*.swp
+
+# Build
+v4/html/index.html
+*mattermost-openapi-v3.yaml
+*mattermost-openapi-v4.yaml
+.npminstall
+node_modules
+playbooks/*.yaml
+!playbooks/tags.yaml
+
+# IDEs
+.idea/

api/.gitpod.yml

@@ -0,0 +1,15 @@
+ports:
+  - port: 8080
+    onOpen: open-browser
+
+tasks:
+  - name: Docs
+    init: make build
+    command: make run
+  - name: Notice
+    command: |
+      clear
+      echo "Once the docs server is running, go to the following URL to view the docs:
+
+      $(gp url 8080)"
+    openMode: split-right

api/.spectral.yaml

@@ -0,0 +1,14 @@
+extends: '@ibm-cloud/openapi-ruleset'
+rules:
+  operation-tags: off
+  property-case-convention: off
+  request-body-object: off
+  operation-operationId: error
+  operation-summary: warn
+  array-responses: off
+  parameter-description: error
+  parameter-description: off
+  parameter-case-convention: info
+  no-$ref-siblings: off
+  enum-case-convention: off
+  path-segment-case-convention: info 

api/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+## Contributing
+
+We're accepting pull requests! Specifically we're looking for documenation on routes defined [here](../server/channels/api4).
+
+All the documentation is written in YAML and found in the [source](v4/source) directory.
+
+* When adding a new route, please add it to the correct file. For example, a channel route will go in [channels.yaml](v4/source/channels.yaml).
+* To add a new tag, please do so in [introduction.yaml](v4/source/introduction.yaml)
+* Definitions should be added to [definitions.yaml](v4/source/definitions.yaml)
+
+There is no strict style guide but please try to follow the example of the existing documentation.
+
+To build the full YAML, run `make build` and it will be output to `html/static/mattermost-openapi.yaml`. To check for syntax, you can copy the contents of that into http://editor.swagger.io/ or you can look into using a commandline or ESLint-based syntax checker.

api/Makefile

@@ -0,0 +1,79 @@
+.PHONY: build build-v4 clean playbooks
+
+V4_YAML = v4/html/static/mattermost-openapi-v4.yaml
+
+V4_SRC = v4/source
+PLAYBOOKS_SRC = playbooks
+
+build: build-v4
+
+build-v4: node_modules playbooks
+	@echo Building mattermost openapi yaml for v4
+
+	@if [ -r $(PLAYBOOKS_SRC)/merged-tags.yaml ]; then cat $(PLAYBOOKS_SRC)/merged-tags.yaml > $(V4_YAML); else cat $(V4_SRC)/introduction.yaml > $(V4_YAML); fi
+	@cat $(V4_SRC)/insights.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/users.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/status.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/teams.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/channels.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/posts.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/preferences.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/files.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/uploads.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/jobs.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/system.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/emoji.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/webhooks.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/saml.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/compliance.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/ldap.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/groups.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/cluster.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/brand.yaml >> $(V4_YAML)
+	@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)
+	@cat $(V4_SRC)/schemes.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/service_terms.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/sharedchannels.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/opengraph.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/reactions.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/actions.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/bots.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/cloud.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/usage.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/permissions.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/imports.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/exports.yaml >> $(V4_YAML)
+	@if [ -r $(PLAYBOOKS_SRC)/paths.yaml ]; then cat $(PLAYBOOKS_SRC)/paths.yaml >> $(V4_YAML); fi
+	@if [ -r $(PLAYBOOKS_SRC)/merged-definitions.yaml ]; then cat $(PLAYBOOKS_SRC)/merged-definitions.yaml >> $(V4_YAML); else cat $(V4_SRC)/definitions.yaml >> $(V4_YAML); fi
+
+	@node_modules/.bin/swagger-cli validate $(V4_YAML)
+	@node_modules/.bin/redoc-cli -t ./v4/html/ssr_template.hbs build ./v4/html/static/mattermost-openapi-v4.yaml -o ./v4/html/index.html --options.noAutoAuth  --options.suppressWarnings
+	@echo Complete
+
+node_modules: package.json $(wildcard package-lock.json)
+	@echo Getting dependencies using npm
+
+	npm install
+	touch $@
+
+run:
+	@echo Starting redoc server
+
+	@node_modules/.bin/redoc-cli -t ./v4/html/ssr_template.hbs serve ./v4/html/static/mattermost-openapi-v4.yaml --options.noAutoAuth  --options.suppressWarnings  --ssr
+
+clean:
+	@echo Cleaning
+
+	rm -rf node_modules
+
+playbooks:
+	@echo Fetching Playbooks OpenAPI spec
+	cd playbooks && node extract.js
+	cd playbooks && node merge-definitions.js ../$(V4_SRC)/definitions.yaml
+	cd playbooks && node merge-tags.js ../$(V4_SRC)/introduction.yaml

api/README.md

@@ -0,0 +1,28 @@
+# Mattermost API Documentation
+
+This repository holds the API reference available at [https://api.mattermost.com](https://api.mattermost.com).
+
+The Mattermost API reference uses the [OpenAPI standard](https://openapis.org/) and the [ReDoc document generator](https://github.com/Rebilly/ReDoc).
+
+All documentation is available under the terms of a [Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/3.0/).
+
+## Contributing
+
+We're accepting pull requests! See something that could be documented better or is missing documentation? Make a PR and we'll gladly accept it.
+
+All the documentation is written in YAML and found in the [v4/source](v4/source) directories. APIv4 documentation is in the [v4 directory](v4).
+APIs for [Playbooks](https://github.com/mattermost/mattermost-plugin-playbooks) are retrieved from GitHub at build time and integrated into the final YAML file.
+
+* When adding a new route, please add it to the correct file. For example, a channel route will go in [channels.yaml](v4/source/channels.yaml).
+* To add a new tag, please do so in [introduction.yaml](v4/source/introduction.yaml)
+* Definitions should be added to [definitions.yaml](v4/source/definitions.yaml)
+
+There is no strict style guide but please try to follow the example of the existing documentation.
+
+To build the full YAML, run `make build` and it will be output to `v4/html/static/mattermost-openapi-v4.yaml`. This will also check syntax using [swagger-cli](https://github.com/APIDevTools/swagger-cli).
+
+To test locally, run `make build`, `make run` and navigate to `http://127.0.0.1:8080`. For any updates to the source files, re-run the same commands.
+
+## Deployment
+
+Deployment is handled automatically by our Jenkins CLI machine. When a pull request is merged it will automatically be deployed to [https://api.mattermost.com](https://api.mattermost.com).

api/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "mattermost-api-reference",
+  "version": "1.0.0",
+  "description": "This respository holds the API reference available at [https://api.mattermost.com](https://api.mattermost.com).",
+  "main": "index.js",
+  "dependencies": {
+    "redoc-cli": "0.13.17",
+    "swagger-cli": "4.0.4",
+    "sync-fetch": "0.4.1",
+    "yaml": "2.1.1"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mattermost/mattermost-api-reference.git"
+  },
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/mattermost/mattermost-api-reference/issues"
+  },
+  "homepage": "https://github.com/mattermost/mattermost-api-reference#readme"
+}

api/playbooks/extract.js

@@ -0,0 +1,55 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+const fetch = require('sync-fetch');
+
+class Extractor {
+    constructor() {}
+
+    /**
+     * Write YAML data to the specified file, optionally indenting all lines by a specified amount
+     * @param filename {String} The file to write the data to
+     * @param data {Record<String, any>} An object that contains the data to be written to the file
+     * @param indent {Number} Number of spaces to left-pad each line with
+     */
+    writeFile(filename, data, indent = 0) {
+        let stringified = YAML.stringify(data, { lineWidth: 0 });
+        if (indent > 0) {
+            stringified = stringified.replace(/^(.*)$/mg, '$1'.padStart(2 + indent)) + "\n";
+        }
+        fs.writeFileSync(filename, stringified);
+        console.log("wrote file " + filename);
+    }
+
+    /**
+     * Extract various parts of an OpenAPI spec into separate files
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        // Fetch the OpenAPI spec
+        const rawSpec = fetch('https://raw.githubusercontent.com/mattermost/mattermost-plugin-playbooks/master/server/api/api.yaml').text();
+        console.log("fetched Playbooks OpenAPI spec");
+        // Parse the OpenAPI spec
+        const parsed = YAML.parse(rawSpec);
+        // Extract paths
+        if ("paths" in parsed) {
+            this.writeFile("paths.yaml", parsed["paths"], 2);
+        }
+        // Extract components.schemas, components.responses, and components.securitySchemes
+        if ("components" in parsed) {
+            /** @type {Record<String,any>} */
+            const components = parsed["components"];
+            if ("schemas" in components) {
+                this.writeFile("schemas.yaml", components["schemas"]);
+            }
+            if ("responses" in components) {
+                this.writeFile("responses.yaml", components["responses"]);
+            }
+            if ("securitySchemes" in components) {
+                this.writeFile("securitySchemes.yaml", components["securitySchemes"]);
+            }
+        }
+    }
+}
+
+new Extractor().run(process.argv);

api/playbooks/merge-definitions.js

@@ -0,0 +1,61 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+
+class MergeDefinitions {
+    constructor() {}
+
+    /**
+     * Write YAML data to the specified file
+     * @param filename {String}
+     * @param data {Record<String, any>}
+     */
+    writeFile(filename, data) {
+        fs.writeFileSync(filename, YAML.stringify(data, { lineWidth: 0 }).trimEnd());
+        console.log("wrote file " + filename);
+    }
+
+    /**
+     * Read a YAML file, parse it, and return the resulting object
+     * @param filename {String} The YAML file to read
+     * @returns {Record<String,any>} The parsed object
+     */
+    readFile(filename) {
+        const rawYaml = fs.readFileSync(filename);
+        console.log("read file " + filename);
+        return YAML.parse(rawYaml.toString());
+    }
+
+    /**
+     * Merge OpenAPI schema definitions
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        if (args.length < 3) {
+            console.error("please specify an input file");
+            return;
+        }
+        if (args[2] === "") {
+            console.error("input file not specified");
+            return;
+        }
+        // read definitions.yaml
+        const parsed = this.readFile(args[2]);
+        // read schemas.yaml
+        const schemas = this.readFile("schemas.yaml");
+        // read responses.yaml
+        const responses = this.readFile("responses.yaml");
+        // read securitySchemes.yaml
+        const securitySchemes = this.readFile("securitySchemes.yaml");
+        // merge schemas with definitions.yaml
+        parsed["components"]["schemas"] = Object.assign(parsed["components"]["schemas"], schemas);
+        // merge responses with definitions.yaml
+        parsed["components"]["responses"] = Object.assign(parsed["components"]["responses"], responses);
+        // merge securitySchemes with definitions.yaml
+        parsed["components"]["securitySchemes"] = Object.assign(parsed["components"]["securitySchemes"], securitySchemes);
+        // write merged definitions to a new file
+        this.writeFile("merged-definitions.yaml", parsed);
+    }
+}
+
+new MergeDefinitions().run(process.argv);

api/playbooks/merge-tags.js

@@ -0,0 +1,53 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+
+class MergeTags {
+    constructor() {}
+
+    /**
+     * Read a YAML file, parse it, and return the resulting object
+     * @param filename {String} The YAML file to read
+     * @returns {Record<String,any>} The parsed object
+     */
+    readFile(filename) {
+        const rawYaml = fs.readFileSync(filename);
+        console.log("read file " + filename);
+        return YAML.parse(rawYaml.toString());
+    }
+
+    /**
+     * Merge OpenAPI tags
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        if (args.length < 3) {
+            console.error("please specify an input file");
+            return;
+        }
+        if (args[2] === "") {
+            console.error("input file not specified");
+            return;
+        }
+        // read introduction.yaml
+        const parsed = this.readFile(args[2]);
+        // read tags.yaml
+        const tags = this.readFile("tags.yaml");
+        if ("tags" in parsed) {
+            parsed["tags"].push(...tags["tags"]);
+        }
+        if ("x-tagGroups" in parsed) {
+            parsed["x-tagGroups"].push(...tags["x-tagGroups"]);
+        }
+        // Convert the modified object back to YAML and remove the trailing "null" as we want the
+        // "paths" field to have no value at this stage of building.
+        const yamlString =
+            YAML.stringify(parsed, { lineWidth: 0 }).
+                replace(/^paths:.*null.*$/mg, "paths: ");
+        // write out to merged-tags.yaml
+        fs.writeFileSync("merged-tags.yaml", yamlString);
+        console.log("wrote file merged-tags.yaml");
+    }
+}
+
+new MergeTags().run(process.argv);

api/playbooks/tags.yaml

@@ -0,0 +1,20 @@
+---
+tags:
+  - name: Playbooks
+    description: Playbooks
+  - name: PlaybookRuns
+    description: Playbook runs
+  - name: Internal
+    description: Internal endpoints
+  - name: Timeline
+    description: Timeline
+  - name: PlaybookAutofollows
+    description: Playbook Autofollows
+x-tagGroups:
+  - name: Playbooks
+    tags:
+      - Playbooks
+      - PlaybookRuns
+      - PlaybookAutofollows
+      - Timeline
+      - Internal

api/v4/html/ssr_template.hbs

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>Mattermost API Reference</title>
+  <!-- needed for adaptive design -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="shortcut icon" href="./static/favicon.ico">
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+    label[type="tag"] {
+        text-transform:  uppercase;
+      }
+      h1{
+        text-transform: capitalize;
+      }
+  </style>
+  {{{redocHead}}}
+  {{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
+</head>
+
+<body>
+  {{{redocHTML}}}
+</body>
+
+</html>

api/v4/source/actions.yaml

@@ -0,0 +1,133 @@
+  /api/v4/actions/dialogs/open:
+    post:
+      tags:
+        - integration_actions
+      summary: Open a dialog
+      description: >
+        Open an interactive dialog using a trigger ID provided by a slash
+        command, or some other action payload. See
+        https://docs.mattermost.com/developer/interactive-dialogs.html for more
+        information on interactive dialogs.
+
+        __Minimum server version: 5.6__
+      operationId: OpenInteractiveDialog
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - trigger_id
+                - url
+                - dialog
+              properties:
+                trigger_id:
+                  type: string
+                  description: Trigger ID provided by other action
+                url:
+                  type: string
+                  description: The URL to send the submitted dialog payload to
+                dialog:
+                  type: object
+                  required:
+                    - title
+                    - elements
+                  description: Post object to create
+                  properties:
+                    callback_id:
+                      type: string
+                      description: Set an ID that will be included when the dialog is
+                        submitted
+                    title:
+                      type: string
+                      description: Title of the dialog
+                    introduction_text:
+                      type: string
+                      description: Markdown formatted introductory paragraph
+                    elements:
+                      type: array
+                      description: Input elements, see
+                        https://docs.mattermost.com/developer/interactive-dialogs.html#elements
+                      items:
+                        type: object
+                    submit_label:
+                      type: string
+                      description: Label on the submit button
+                    notify_on_cancel:
+                      type: boolean
+                      description: Set true to receive payloads when user cancels a dialog
+                    state:
+                      type: string
+                      description: Set some state to be echoed back with the dialog
+                        submission
+        description: Metadata for the dialog to be opened
+        required: true
+      responses:
+        "200":
+          description: Dialog open successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+  /api/v4/actions/dialogs/submit:
+    post:
+      tags:
+        - integration_actions
+      summary: Submit a dialog
+      description: >
+        Endpoint used by the Mattermost clients to submit a dialog. See
+        https://docs.mattermost.com/developer/interactive-dialogs.html for more
+        information on interactive dialogs.
+
+        __Minimum server version: 5.6__
+      operationId: SubmitInteractiveDialog
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - url
+                - submission
+                - channel_id
+                - team_id
+              properties:
+                url:
+                  type: string
+                  description: The URL to send the submitted dialog payload to
+                channel_id:
+                  type: string
+                  description: Channel ID the user submitted the dialog from
+                team_id:
+                  type: string
+                  description: Team ID the user submitted the dialog from
+                submission:
+                  type: object
+                  description: String map where keys are element names and values are the
+                    element input values
+                callback_id:
+                  type: string
+                  description: Callback ID sent when the dialog was opened
+                state:
+                  type: string
+                  description: State sent when the dialog was opened
+                cancelled:
+                  type: boolean
+                  description: Set to true if the dialog was cancelled
+        description: Dialog submission data
+        required: true
+      responses:
+        "200":
+          description: Dialog submission 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/source/bleve.yaml

@@ -0,0 +1,28 @@
+  /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"

api/v4/source/bots.yaml

@@ -0,0 +1,800 @@
+  /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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $resp = $driver->getBotModel()->createBot([
+                "username" => "userbot",
+                "display_name" => "AwesomeBot",
+                "description" => "test bot"
+            ]);
+
+            if ($resp->getStatusCode() == 200) {
+                $createdBot = json_decode($resp->getBody());
+            }
+    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. There is a maximum limit of 200 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 consitered
+            orphaned if it's 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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $resp = $driver->getBotModel()->getBots([
+                "page" => 0,
+                "per_page" => 60,
+                "include_deleted" => true,
+                "only_orphaned" => true,
+            ]);
+
+            if ($resp->getStatusCode() == 200) {
+                $bots = json_decode($resp->getBody());
+            }
+  "/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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+            $resp = $driver->getBotModel()->patchBot($botUserID, [
+                "username" => "userbot2",
+                "display_name" => "AwesomeBot2",
+                "description" => "test bot2"
+            ]);
+
+            if ($resp->getStatusCode() == 200) {
+                $bot = json_decode($resp->getBody());
+            }
+    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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+            $resp = $driver->getBotModel()->getBot($botUserID, [
+                "include_deleted" => true,
+            ]);
+
+            if ($resp->getStatusCode() == 200) {
+                $bot = json_decode($resp->getBody());
+            }
+  "/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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+            $resp = $driver->getBotModel()->disableBot($botUserID);
+
+            if ($resp->getStatusCode() == 200) {
+                $disabledBot = json_decode($resp->getBody());
+            }
+  "/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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+            $resp = $driver->getBotModel()->enableBot($botUserID);
+
+            if ($resp->getStatusCode() == 200) {
+                $enabledBot = json_decode($resp->getBody());
+            }
+  "/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"
+      x-code-samples:
+        - lang: PHP
+          source: |
+            require 'vendor/autoload.php';
+
+            use \Gnello\Mattermost\Driver;
+
+            $container = new \Pimple\Container([
+                "driver" => [
+                    "url" => "https://your-mattermost-url.com",
+                    "login_id" => "email@domain.com",
+                    "password" => "Password1",
+                ]
+            ]);
+
+            $driver = new Driver($container);
+            $driver->authenticate();
+
+            $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+            $userID = "adWv1qPZmHdtxk7Lmqh6RtxWxS";
+
+            $resp = $driver->getBotModel()->assignBotToUser($botUserID, $userID);
+
+            if ($resp->getStatusCode() == 200) {
+                $assignedBot = json_decode($resp->getBody());
+            }
+  "/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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            botUserID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            data, resp := Client.GetBotIconImage(botUserID)
+        - lang: PHP
+          source: |
+             require 'vendor/autoload.php';
+
+             use \Gnello\Mattermost\Driver;
+
+             $container = new \Pimple\Container([
+                 "driver" => [
+                     "url" => "https://your-mattermost-url.com",
+                     "login_id" => "email@domain.com",
+                     "password" => "Password1",
+                 ]
+             ]);
+
+             $driver = new Driver($container);
+             $driver->authenticate();
+
+             $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+             $resp = $driver->getBotModel()->getBotIcon($botUserID);
+
+             if ($resp->getStatusCode() == 200) {
+                 $data = json_decode($resp->getBody());
+             }
+    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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import (
+              "io/ioutil"
+              "log"
+
+              "github.com/mattermost/mattermost-server/v5/model"
+            )
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            data, err := ioutil.ReadFile("icon_image.svg")
+            if err != nil {
+              log.Fatal(err)
+            }
+
+            botUserID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            ok, resp := Client.SetBotIconImage(botUserID, data)
+        - lang: PHP
+          source: |
+              require 'vendor/autoload.php';
+
+              use \Gnello\Mattermost\Driver;
+
+              $container = new \Pimple\Container([
+                  "driver" => [
+                      "url" => "https://your-mattermost-url.com",
+                      "login_id" => "email@domain.com",
+                      "password" => "Password1",
+                  ]
+              ]);
+
+              $driver = new Driver($container);
+              $driver->authenticate();
+
+              $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+              $resource = fopen("icon_image.svg", 'rb');
+
+              if ($resource === false) {
+                  throw new \Exeption("Failure.");
+              }
+
+              $data = new \GuzzleHttp\Psr7\Stream($resource);
+
+              $resp = $driver->getBotModel()->setBotIcon($botUserID, [
+                  "image" => $data,
+              ]);
+
+              fclose($resource);
+
+              if ($resp->getStatusCode() == 200) {
+                  $ok = json_decode($resp->getBody())->status;
+              }
+    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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            botUserID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            ok, resp := Client.DeleteBotIconImage(botUserID)
+        - lang: PHP
+          source: |
+              require 'vendor/autoload.php';
+
+              use \Gnello\Mattermost\Driver;
+
+              $container = new \Pimple\Container([
+                  "driver" => [
+                      "url" => "https://your-mattermost-url.com",
+                      "login_id" => "email@domain.com",
+                      "password" => "Password1",
+                  ]
+              ]);
+
+              $driver = new Driver($container);
+              $driver->authenticate();
+
+              $botUserID = "4xp9fdt77pncbef59f4k1qe83o";
+
+              $resp = $driver->getBotModel()->deleteBotIcon($botUserID);
+
+              if ($resp->getStatusCode() == 200) {
+                  $ok = json_decode($resp->getBody())->status;
+              }
+  "/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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            userId := "BbaYBYDV5IDOZFiJGBSzkw1k5u"
+            patch := &model.UserPatch{}
+            patch.Email = model.NewString("test@domain.com")
+            patch.Username = model.NewString("testUsername")
+            patch.Password = model.NewString("password")
+
+            user, resp := Client.ConvertBotToUser(userId, userPatch, false)

api/v4/source/brand.yaml

@@ -0,0 +1,129 @@
+  /api/v4/brand/image:
+    get:
+      tags:
+        - brand
+      summary: Get brand image
+      description: >
+        Get the previously uploaded brand image. Returns 404 if no brand image
+        has been uploaded.
+
+        ##### Permissions
+
+        No permission required.
+      operationId: GetBrandImage
+      responses:
+        "200":
+          description: Brand image retrieval successful
+          content:
+            application/json:
+              schema:
+                type: string
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // GetBrandImage
+            img, err := Client.GetBrandImage()
+    post:
+      tags:
+        - brand
+      summary: Upload brand image
+      description: |
+        Uploads a brand image.
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: UploadBrandImage
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                image:
+                  description: The image to be uploaded
+                  type: string
+                  format: binary
+              required:
+                - image
+      responses:
+        "201":
+          description: Brand image upload 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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            file, err := os.Open("<Your image>")
+            if err != nil {
+              return err
+            }
+            defer file.Close()
+
+            data := &bytes.Buffer{}
+            if _, err := io.Copy(data, file); err != nil {
+              return err
+            }
+
+            ok, resp := Client.UploadBrandImage(data.Bytes())
+    delete:
+      tags:
+        - brand
+      summary: Delete current brand image
+      description: >
+        Deletes the previously uploaded brand image. Returns 404 if no brand
+        image has been uploaded.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+        __Minimum server version: 5.6__
+      operationId: DeleteBrandImage
+      responses:
+        "200":
+          description: Brand image succesfully deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // Delete brand image
+            resp := Client.DeleteBrandImage()

api/v4/source/cloud.yaml

@@ -0,0 +1,357 @@
+  /api/v4/cloud/limits:
+    get:
+      tags:
+        - cloud
+      summary: Get cloud workspace limits
+      description: >
+        Retrieve any cloud workspace limits applicable to this instance.
+
+        ##### Permissions
+
+        Must be authenticated and be licensed for Cloud.
+
+        __Minimum server version__: 7.0
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: GetCloudLimits
+      responses:
+        "200":
+          description: Cloud workspace limits returned successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProductLimits"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/products:
+    get:
+      tags:
+        - cloud
+      summary: Get cloud products
+      description: >
+        Retrieve a list of all products that are offered for Mattermost Cloud.
+
+        ##### 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: GetCloudProducts
+      responses:
+        "200":
+          description: Cloud products returned successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Product"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $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:
+        - cloud
+      summary: Get cloud customer
+      description: >
+        Retrieves the customer information for the Mattermost Cloud customer bound to this 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: GetCloudCustomer
+      responses:
+        "200":
+          description: Cloud customer returned successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudCustomer"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    put:
+      tags:
+        - cloud
+      summary: Update cloud customer
+      description: >
+        Updates the customer information for the Mattermost Cloud customer bound to this installation.
+
+        ##### Permissions
+
+        Must have `manage_system` permission and be licensed for Cloud.
+
+        __Minimum server version__: 5.29
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: UpdateCloudCustomer
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                email:
+                  type: string
+                contact_first_name:
+                  type: string
+                contact_last_name:
+                  type: string
+                num_employees:
+                  type: string
+        description: Customer patch including information to update
+        required: true
+      responses:
+        "200":
+          description: Cloud customer updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudCustomer"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/customer/address:
+    put:
+      tags:
+        - cloud
+      summary: Update cloud customer address
+      description: >
+        Updates the company address for the Mattermost Cloud customer bound to this installation.
+
+        ##### Permissions
+
+        Must have `manage_system` permission and be licensed for Cloud.
+
+        __Minimum server version__: 5.29
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: UpdateCloudCustomerAddress
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Address"
+        description: Company address information to update
+        required: true
+      responses:
+        "200":
+          description: Cloud customer address updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudCustomer"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/subscription:
+    get:
+      tags:
+        - cloud
+      summary: Get cloud subscription
+      description: >
+        Retrieves the subscription information for the Mattermost Cloud customer bound to this 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: GetSubscription
+      responses:
+        "200":
+          description: Cloud subscription returned successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Subscription"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/subscription/invoices:
+    get:
+      tags:
+        - cloud
+      summary: Get cloud subscription invoices
+      description: >
+        Retrieves the invoices for the subscription bound to this installation.
+
+        ##### Permissions
+
+        Must have `manage_system` permission and be licensed for Cloud.
+
+        __Minimum server version__: 5.30
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: GetInvoicesForSubscription
+      responses:
+        "200":
+          description: Subscription invoices returned successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Invoice"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/subscription/invoices/{invoice_id}/pdf:
+    get:
+      tags:
+        - cloud
+      summary: Get cloud invoice PDF
+      description: >
+        Retrieves the PDF for the invoice passed as parameter
+
+        ##### Permissions
+
+        Must have `manage_system` permission and be licensed for Cloud.
+
+        __Minimum server version__: 5.30
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: GetInvoiceForSubscriptionAsPdf
+      parameters:
+        - name: invoice_id
+          in: path
+          description: Invoice ID
+          required: true
+          schema:
+            type: string
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/cloud/webhook:
+    post:
+      tags:
+        - cloud
+      summary: POST endpoint for CWS Webhooks
+      description: >
+        An endpoint for processing webhooks from the Customer Portal
+
+        ##### Permissions
+
+        This endpoint should only be accessed by CWS, in a Mattermost Cloud instance
+
+        __Minimum server version__: 5.30
+        __Note:__ This is intended for internal use and is subject to change.
+      operationId: PostEndpointForCwsWebhooks
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+

api/v4/source/cluster.yaml

@@ -0,0 +1,24 @@
+  /api/v4/cluster/status:
+    get:
+      tags:
+        - cluster
+      summary: Get cluster status
+      description: >
+        Get a set of information for each node in the cluster, useful for
+        checking the status and health of each node.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: GetClusterStatus
+      responses:
+        "200":
+          description: Cluster status retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ClusterInfo"
+        "403":
+          $ref: "#/components/responses/Forbidden"

api/v4/source/commands.yaml

@@ -0,0 +1,512 @@
+  /api/v4/commands:
+    post:
+      tags:
+        - commands
+      summary: Create a command
+      description: |
+        Create a command for a team.
+        ##### Permissions
+        `manage_slash_commands` for the team the command is in.
+      operationId: CreateCommand
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - team_id
+                - method
+                - trigger
+                - url
+              properties:
+                team_id:
+                  type: string
+                  description: Team ID to where the command should be created
+                method:
+                  type: string
+                  description: "`'P'` for post request, `'G'` for get request"
+                trigger:
+                  type: string
+                  description: Activation word to trigger the command
+                url:
+                  type: string
+                  description: The URL that the command will make the request
+        description: command to be created
+        required: true
+      responses:
+        "201":
+          description: Command creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Command"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            newCmd := &model.Command {
+              TeamId:       <TEAMID>,
+              URL:          "http://nowhere.com",
+              Method:       model.COMMAND_METHOD_POST,
+              Trigger:      "trigger",
+              AutoComplete: false,
+              Description:  "Description",
+              DisplayName:  "Display name",
+              IconURL:      "IconURL",
+              Username:     "Username"
+            }
+
+            // CreateCommand
+            createdCmd, resp := Client.CreateCommand(newCmd)
+    get:
+      tags:
+        - commands
+      summary: List commands for a team
+      description: |
+        List commands for a team.
+        ##### Permissions
+        `manage_slash_commands` if need list custom commands.
+      operationId: ListCommands
+      parameters:
+        - name: team_id
+          in: query
+          description: The team id.
+          schema:
+            type: string
+        - name: custom_only
+          in: query
+          description: >
+            To get only the custom commands. If set to false will get the custom
+
+            if the user have access plus the system commands, otherwise just the system commands.
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: List Commands retrieve successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Command"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+
+            // ListCommands
+
+            // The second parameter is to set if you want only custom commands (true) or defaults commands (false)
+
+            listCommands, resp := Client.ListCommands(<TEAMID>, true)
+  "/api/v4/teams/{team_id}/commands/autocomplete":
+    get:
+      tags:
+        - commands
+      summary: List autocomplete commands
+      description: |
+        List autocomplete commands in the team.
+        ##### Permissions
+        `view_team` for the team.
+      operationId: ListAutocompleteCommands
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Autocomplete commands retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Command"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // ListAutocompleteCommands
+            listCommands, resp := Client.ListAutocompleteCommands(<TEAMID>)
+  '/teams/{team_id}/commands/autocomplete_suggestions':
+    get:
+      tags:
+        - commands
+      summary: List commands' autocomplete data
+      description: |
+        List commands' autocomplete data for the team.
+        ##### Permissions
+        `view_team` for the team.
+        __Minimum server version__: 5.24
+      operationId: ListCommandAutocompleteSuggestions
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+        - name: user_input
+          in: query
+          description: String inputted by the user.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Commands' autocomplete data retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/AutocompleteSuggestion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: 'Go'
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // ListCommandAutocompleteSuggestions
+            teamID := "4xp9fdt77pncbef59f4k1qe83o"
+            userInput := "/jira"
+            listCommands, resp := Client.ListCommandAutocompleteSuggestions(userInput, teamID)
+  "/api/v4/commands/{command_id}":
+    get:
+      tags:
+        - commands
+      summary: Get a command
+      description: >
+        Get a command definition based on command id string.
+
+        ##### Permissions
+
+        Must have `manage_slash_commands` permission for the team the command is in.
+
+
+        __Minimum server version__: 5.22
+      operationId: GetCommandById
+      parameters:
+        - in: path
+          name: command_id
+          description: ID of the command to get
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Command get successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Command"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // GetCommand
+            cmd, resp := Client.GetCommand(<COMMANDID>)
+    put:
+      tags:
+        - commands
+      summary: Update a command
+      description: >
+        Update a single command based on command id string and Command struct.
+
+        ##### Permissions
+
+        Must have `manage_slash_commands` permission for the team the command is in.
+      operationId: UpdateCommand
+      parameters:
+        - in: path
+          name: command_id
+          description: ID of the command to update
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Command"
+        required: true
+      responses:
+        "200":
+          description: Command updated successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Command"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            cmdToUpdate := &model.Command{
+              CreatorId: <USERID>,
+              TeamId:    <TEAMID>,
+              URL:       "<http://nowhere.com/change>",
+              Trigger:   <NEWTRIGGERNAME>,
+              Id:        <COMMANDID>,
+            }
+
+            // UpdateCommand
+            listCommands, resp := Client.UpdateCommand(cmdToUpdate)
+    delete:
+      tags:
+        - commands
+      summary: Delete a command
+      description: >
+        Delete a command based on command id string.
+
+        ##### Permissions
+
+        Must have `manage_slash_commands` permission for the team the command is in.
+      operationId: DeleteCommand
+      parameters:
+        - in: path
+          name: command_id
+          description: ID of the command to delete
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Command 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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // DeleteCommand
+            ok, resp := Client.DeleteCommand(<COMMANDID>)
+  "/api/v4/commands/{command_id}/move":
+    put:
+      tags:
+        - commands
+      summary: Move a command
+      description: >
+        Move a command to a different team based on command id string.
+
+        ##### Permissions
+
+        Must have `manage_slash_commands` permission for the team the command is currently in and the destination team.
+
+
+        __Minimum server version__: 5.22
+      operationId: MoveCommand
+      parameters:
+        - in: path
+          name: command_id
+          description: ID of the command to move
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                team_id:
+                  type: string
+                  description: Destination teamId
+        required: true
+      responses:
+        "200":
+          description: Command move 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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // MoveCommand
+            ok, resp := Client.MoveCommand(<TEAMID>,<COMMANDID>)
+  "/api/v4/commands/{command_id}/regen_token":
+    put:
+      tags:
+        - commands
+      summary: Generate a new token
+      description: >
+        Generate a new token for the command based on command id string.
+
+        ##### Permissions
+
+        Must have `manage_slash_commands` permission for the team the command is in.
+      operationId: RegenCommandToken
+      parameters:
+        - in: path
+          name: command_id
+          description: ID of the command to generate the new token
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Token generation successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    description: The new token
+                    type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            // RegenCommandToken
+            newToken, resp := Client.RegenCommandToken(<COMMANDID>)
+  /api/v4/commands/execute:
+    post:
+      tags:
+        - commands
+      summary: Execute a command
+      description: >
+        Execute a command on a team.
+
+        ##### Permissions
+
+        Must have `use_slash_commands` permission for the team the command is in.
+      operationId: ExecuteCommand
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - channel_id
+                - command
+              properties:
+                channel_id:
+                  type: string
+                  description: Channel Id where the command will execute
+                command:
+                  type: string
+                  description: "The slash command to execute, including parameters. Eg, `'/echo bounces around the room'`"
+        description: command to be executed
+        required: true
+      responses:
+        "200":
+          description: Command execution successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CommandResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/compliance.yaml

@@ -0,0 +1,127 @@
+  /api/v4/compliance/reports:
+    post:
+      tags:
+        - compliance
+      summary: Create report
+      description: |
+        Create and save a compliance report.
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: CreateComplianceReport
+      responses:
+        "201":
+          description: Compliance report creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Compliance"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    get:
+      tags:
+        - compliance
+      summary: Get reports
+      description: >
+        Get a list of compliance reports previously created by page, selected
+        with `page` and `per_page` query parameters.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: GetComplianceReports
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of reports per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Compliance reports retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Compliance"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/compliance/reports/{report_id}":
+    get:
+      tags:
+        - compliance
+      summary: Get a report
+      description: |
+        Get a compliance reports previously created.
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: GetComplianceReport
+      parameters:
+        - name: report_id
+          in: path
+          description: Compliance report GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Compliance report retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Compliance"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/compliance/reports/{report_id}/download":
+    get:
+      tags:
+        - compliance
+      summary: Download a report
+      description: |
+        Download the full contents of a report as a file.
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: DownloadComplianceReport
+      parameters:
+        - name: report_id
+          in: path
+          description: Compliance report GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The compliance report file
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/dataretention.yaml

@@ -0,0 +1,676 @@
+  /api/v4/data_retention/policy:
+    get:
+      tags:
+        - data retention
+      summary: Get the global data retention policy
+      description: |
+        Gets the current global data retention policy details from the server,
+        including what data should be purged and the cutoff times for each data
+        type that should be purged.
+        
+        __Minimum server version__: 4.3
+        
+        ##### Permissions
+        Requires an active session but no other permissions.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetDataRetentionPolicy
+      responses:
+        "200":
+          description: Global data retention policy details retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GlobalDataRetentionPolicy"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/data_retention/policies_count:
+    get:
+      tags:
+        - data retention
+      summary: Get the number of granular data retention policies
+      description: |
+        Gets the number of granular (i.e. team or channel-specific) data retention
+        policies from the server.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetDataRetentionPoliciesCount
+      responses:
+        "200":
+          description: Number of retention policies retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total_count:
+                    type: integer
+                    description: The number of granular retention policies.
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/data_retention/policies:
+    get:
+      tags:
+        - data retention
+      summary: Get the granular data retention policies
+      description: |
+        Gets details about the granular (i.e. team or channel-specific) data retention
+        policies from the server.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetDataRetentionPolicies
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of policies per page. There is a maximum limit of 200 per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Retention policies' details retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    post:
+      tags:
+        - data retention
+      summary: Create a new granular data retention policy
+      description: |
+        Creates a new granular data retention policy with the specified display
+        name and post duration.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: CreateDataRetentionPolicy
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DataRetentionPolicyCreate"
+      responses:
+        "201":
+          description: Retention policy successfully created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/data_retention/policies/{policy_id}":
+    get:
+      tags:
+        - data retention
+      summary: Get a granular data retention policy
+      description: |
+        Gets details about a granular data retention policies by ID.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetDataRetentionPolicyByID
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Retention policy's details retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    patch:
+      tags:
+        - data retention
+      summary: Patch a granular data retention policy
+      description: |
+        Patches (i.e. replaces the fields of) a granular data retention policy.
+        If any fields are omitted, they will not be changed.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: PatchDataRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DataRetentionPolicyWithTeamAndChannelIds"
+      responses:
+        "200":
+          description: Retention policy successfully patched.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - data retention
+      summary: Delete a granular data retention policy
+      description: |
+        Deletes a granular data retention policy.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: DeleteDataRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Retention policy successfully deleted.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"  
+  "/api/v4/data_retention/policies/{policy_id}/teams":
+    get:
+      tags:
+        - data retention
+      summary: Get the teams for a granular data retention policy
+      description: |
+        Gets the teams to which a granular data retention policy is applied.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetTeamsForRetentionPolicy
+      parameters:
+        - name: policy_id
+          in: path
+          description: The ID of the granular retention policy.
+          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 teams per page. There is a maximum limit of 200 per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Teams for retention policy successfully retrieved.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Team"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    post:
+      tags:
+        - data retention
+      summary: Add teams to a granular data retention policy
+      description: |
+        Adds teams to a granular data retention policy.
+        
+         __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: AddTeamsToRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+                description: The IDs of the teams to add to the policy.
+      responses:
+        "200":
+          description: Teams successfully added to retention policy.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - data retention
+      summary: Delete teams from a granular data retention policy
+      description: |
+        Delete teams from a granular data retention policy.
+        
+         __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: RemoveTeamsFromRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+                description: The IDs of the teams to remove from the policy.
+      responses:
+        "200":
+          description: Teams successfully deleted from retention policy.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/data_retention/policies/{policy_id}/teams/search":
+    post:
+      tags:
+        - data retention
+      summary: Search for the teams in a granular data retention policy
+      description: |
+        Searches for the teams to which a granular data retention policy is applied.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: SearchTeamsForRetentionPolicy
+      parameters:
+        - name: policy_id
+          in: path
+          description: The ID of the granular retention policy.
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                term:
+                  type: string
+                  description: The search term to match against the name or display name of teams
+      responses:
+        "200":
+          description: Teams for retention policy successfully retrieved.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Team"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/data_retention/policies/{policy_id}/channels":
+    get:
+      tags:
+        - data retention
+      summary: Get the channels for a granular data retention policy
+      description: |
+        Gets the channels to which a granular data retention policy is applied.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: GetChannelsForRetentionPolicy
+      parameters:
+        - name: policy_id
+          in: path
+          description: The ID of the granular retention policy.
+          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 channels per page. There is a maximum limit of 200 per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Channels for retention policy successfully retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelListWithTeamData"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    post:
+      tags:
+        - data retention
+      summary: Add channels to a granular data retention policy
+      description: |
+        Adds channels to a granular data retention policy.
+        
+         __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: AddChannelsToRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+                description: The IDs of the channels to add to the policy.
+      responses:
+        "200":
+          description: Channels successfully added to retention policy.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - data retention
+      summary: Delete channels from a granular data retention policy
+      description: |
+        Delete channels from a granular data retention policy.
+        
+         __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_write_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: RemoveChannelsFromRetentionPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the granular retention policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+                description: The IDs of the channels to add to the policy.
+      responses:
+        "200":
+          description: Channels successfully deleted from retention policy.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/data_retention/policies/{policy_id}/channels/search":
+    post:
+      tags:
+        - data retention
+      summary: Search for the channels in a granular data retention policy
+      description: |
+        Searches for the channels to which a granular data retention policy is applied.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+        Must have the `sysconsole_read_compliance_data_retention` permission.
+
+        ##### License
+        Requires an E20 license.
+      operationId: SearchChannelsForRetentionPolicy
+      parameters:
+        - name: policy_id
+          in: path
+          description: The ID of the granular retention policy.
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                term:
+                  type: string
+                  description: The string to search in the channel name, display name, and purpose.
+                team_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: >
+                    Filters results to channels belonging to the given team ids
+                public:
+                  type: boolean
+                  description: >
+                    Filters results to only return Public / Open channels, can be used in conjunction
+                    with `private` to return both `public` and `private` channels
+                private:
+                  type: boolean
+                  description: >
+                    Filters results to only return Private channels, can be used in conjunction
+                    with `public` to return both `private` and `public` channels
+                deleted:
+                  type: boolean
+                  description: >
+                    Filters results to only return deleted / archived channels
+      responses:
+        "200":
+          description: Channels for retention policy successfully retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelListWithTeamData"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/elasticsearch.yaml

@@ -0,0 +1,61 @@
+  /api/v4/elasticsearch/test:
+    post:
+      tags:
+        - elasticsearch
+      summary: Test Elasticsearch configuration
+      description: >
+        Test the current Elasticsearch configuration to see if the Elasticsearch
+        server can be contacted successfully.
+
+        Optionally provide a configuration in the request body to test. If no valid configuration is present in the
+
+        request body the current server configuration will be tested.
+
+
+        __Minimum server version__: 4.1
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: TestElasticsearch
+      responses:
+        "200":
+          description: Elasticsearch test successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/elasticsearch/purge_indexes:
+    post:
+      tags:
+        - elasticsearch
+      summary: Purge all Elasticsearch indexes
+      description: >
+        Deletes all Elasticsearch indexes and their contents. After calling this
+        endpoint, it is
+
+        necessary to schedule a new Elasticsearch indexing job to repopulate the indexes.
+
+        __Minimum server version__: 4.1
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: PurgeElasticsearchIndexes
+      responses:
+        "200":
+          description: Indexes purged successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/emoji.yaml

@@ -0,0 +1,308 @@
+  /api/v4/emoji:
+    post:
+      tags:
+        - emoji
+      summary: Create a custom emoji
+      description: |
+        Create a custom emoji for the team.
+        ##### Permissions
+        Must be authenticated.
+      operationId: CreateEmoji
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                image:
+                  description: A file to be uploaded
+                  type: string
+                  format: binary
+                emoji:
+                  description: A JSON object containing a `name` field with the name of the
+                    emoji and a `creator_id` field with the id of the
+                    authenticated user.
+                  type: string
+              required:
+                - image
+                - emoji
+      responses:
+        "201":
+          description: Emoji creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "413":
+          $ref: "#/components/responses/TooLarge"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    get:
+      tags:
+        - emoji
+      summary: Get a list of custom emoji
+      description: >
+        Get a page of metadata for custom emoji on the system. Since server
+        version 4.7, sort using the `sort` query parameter.
+
+        ##### Permissions
+
+        Must be authenticated.
+      operationId: GetEmojiList
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of emojis per page.
+          schema:
+            type: integer
+            default: 60
+        - name: sort
+          in: query
+          description: Either blank for no sorting or "name" to sort by emoji names.
+            Minimum server version for sorting is 4.7.
+          schema:
+            type: string
+            default: ""
+      responses:
+        "200":
+          description: Emoji list retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/emoji/{emoji_id}":
+    get:
+      tags:
+        - emoji
+      summary: Get a custom emoji
+      description: |
+        Get some metadata for a custom emoji.
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetEmoji
+      parameters:
+        - name: emoji_id
+          in: path
+          description: Emoji GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Emoji retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - emoji
+      summary: Delete a custom emoji
+      description: >
+        Delete a custom emoji.
+
+        ##### Permissions
+
+        Must have the `manage_team` or `manage_system` permissions or be the user who created the emoji.
+      operationId: DeleteEmoji
+      parameters:
+        - name: emoji_id
+          in: path
+          description: Emoji GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Emoji delete successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/emoji/name/{emoji_name}":
+    get:
+      tags:
+        - emoji
+      summary: Get a custom emoji by name
+      description: |
+        Get some metadata for a custom emoji using its name.
+        ##### Permissions
+        Must be authenticated.
+
+        __Minimum server version__: 4.7
+      operationId: GetEmojiByName
+      parameters:
+        - name: emoji_name
+          in: path
+          description: Emoji name
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Emoji retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/emoji/{emoji_id}/image":
+    get:
+      tags:
+        - emoji
+      summary: Get custom emoji image
+      description: |
+        Get the image for a custom emoji.
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetEmojiImage
+      parameters:
+        - name: emoji_id
+          in: path
+          description: Emoji GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Emoji image retrieval successful
+        "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/emoji/search:
+    post:
+      tags:
+        - emoji
+      summary: Search custom emoji
+      description: >
+        Search for custom emoji by name based on search criteria provided in the
+        request body. A maximum of 200 results are returned.
+
+        ##### Permissions
+
+        Must be authenticated.
+
+
+        __Minimum server version__: 4.7
+      operationId: SearchEmoji
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - term
+              properties:
+                term:
+                  description: The term to match against the emoji name.
+                  type: string
+                prefix_only:
+                  description: Set to only search for names starting with the search term.
+                  type: string
+        description: Search criteria
+        required: true
+      responses:
+        "200":
+          description: Emoji list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/emoji/autocomplete:
+    get:
+      tags:
+        - emoji
+      summary: Autocomplete custom emoji
+      description: >
+        Get a list of custom emoji with names starting with or matching the
+        provided name. Returns a maximum of 100 results.
+
+        ##### Permissions
+
+        Must be authenticated.
+
+
+        __Minimum server version__: 4.7
+      operationId: AutocompleteEmoji
+      parameters:
+        - name: name
+          in: query
+          description: The emoji name to search.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Emoji list retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Emoji"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/exports.yaml

@@ -0,0 +1,132 @@
+  "/api/v4/exports":
+    get:
+      tags:
+        - exports
+      summary: List export files
+      description: >
+        Lists all available export files.
+
+        __Minimum server version__: 5.33
+
+        ##### Permissions
+
+        Must have `manage_system` permissions.
+      operationId: ListExports
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            exports, response := Client.ListExports()
+        - lang: Curl
+          source: |
+            curl 'http://localhost:8065/api/v4/exports' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'
+  "/api/v4/exports/{export_name}":
+    get:
+      tags:
+        - exports
+      summary: Download an export file
+      description: |
+        Downloads an export file.
+
+
+        __Minimum server version__: 5.33
+
+        ##### Permissions
+
+        Must have `manage_system` permissions.
+      operationId: DownloadExport
+      parameters:
+        - name: export_name
+          in: path
+          description: The name of the export file to download
+          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"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import (
+              "os"
+              
+              "github.com/mattermost/mattermost-server/v5/model"
+            }
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            outFile, _ := os.Create("export.zip")
+
+            n, response := Client.DownloadExport("export.zip", outFile, 0)
+        - lang: Curl
+          source: |
+            curl 'http://localhost:8065/api/v4/exports/export.zip' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'
+    delete:
+      tags:
+        - exports
+      summary: Delete an export file
+      description: |
+        Deletes an export file.
+
+
+        __Minimum server version__: 5.33
+
+        ##### Permissions
+
+        Must have `manage_system` permissions.
+      operationId: DeleteExport
+      parameters:
+        - name: export_name
+          in: path
+          description: The name of the export file to delete
+          required: true
+          schema:
+            type: string
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            ok, response := Client.DeleteExport("export.zip")
+        - lang: Curl
+          source: |
+            curl -X DELETE 'http://localhost:8065/api/v4/exports/export.zip' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'

api/v4/source/files.yaml

@@ -0,0 +1,520 @@
+  /api/v4/files:
+    post:
+      tags:
+        - files
+      summary: Upload a file
+      description: >
+        Uploads a file that can later be attached to a post.
+
+
+        This request can either be a multipart/form-data request with a channel_id, files and optional
+
+        client_ids defined in the FormData, or it can be a request with the channel_id and filename
+
+        defined as query parameters with the contents of a single file in the body of the request.
+
+
+        Only multipart/form-data requests are supported by server versions up to and including 4.7.
+
+        Server versions 4.8 and higher support both types of requests.
+
+
+        ##### Permissions
+
+        Must have `upload_file` permission.
+      operationId: UploadFile
+      parameters:
+        - name: channel_id
+          in: query
+          description: The ID of the channel that this file will be uploaded to
+          required: false
+          schema:
+            type: string
+        - name: filename
+          in: query
+          description: The name of the file to be uploaded
+          required: false
+          schema:
+            type: string
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                files:
+                  description: A file to be uploaded
+                  type: string
+                  format: binary
+                channel_id:
+                  description: The ID of the channel that this file will be uploaded to
+                  type: string
+                client_ids:
+                  description: A unique identifier for the file that will be returned in
+                    the response
+                  type: string
+      responses:
+        "201":
+          description: Corresponding lists of the provided client_ids and the metadata that
+            has been stored in the database for each one
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  file_infos:
+                    description: A list of file metadata that has been stored in the
+                      database
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/FileInfo"
+                  client_ids:
+                    description: A list of the client_ids that were provided in the request
+                    type: array
+                    items:
+                      type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "413":
+          $ref: "#/components/responses/TooLarge"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+
+            file, err := os.Open("file.png")
+
+            if err != nil {
+              fmt.Fprintf(os.Stderr, "%v\n", err)
+            }
+
+            defer file.Close();
+
+
+            buf := bytes.NewBuffer(nil)
+
+            io.Copy(buf, file)
+
+            data := buf.Bytes()
+
+
+            channelID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            filename := "file.png"
+
+
+            fileUploadResponse, response := Client.UploadFile(data, channelID, filename)
+        - lang: Curl
+          source: |
+            curl -F 'files=@PATH/TO/LOCAL/FILE' \
+            -F 'channel_id=CHANNEL_ID' \
+            --header 'authorization: Bearer c49adc55z3f53ck7xtp8ebq1ir'
+            https://your-mattermost-url.com/api/v4/files
+  "/api/v4/files/{file_id}":
+    get:
+      tags:
+        - files
+      summary: Get a file
+      description: |
+        Gets a file that has been uploaded previously.
+        ##### Permissions
+        Must have `read_channel` permission or be uploader of the file.
+      operationId: GetFile
+      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":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            fileID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            data, resp := Client.GetFile(fileID)
+  "/api/v4/files/{file_id}/thumbnail":
+    get:
+      tags:
+        - files
+      summary: Get a file's thumbnail
+      description: |
+        Gets a file's thumbnail.
+        ##### Permissions
+        Must have `read_channel` permission or be uploader of the file.
+      operationId: GetFileThumbnail
+      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":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            fileID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            data, resp := Client.GetFileThumbnail(fileID)
+  "/api/v4/files/{file_id}/preview":
+    get:
+      tags:
+        - files
+      summary: Get a file's preview
+      description: |
+        Gets a file's preview.
+        ##### Permissions
+        Must have `read_channel` permission or be uploader of the file.
+      operationId: GetFilePreview
+      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":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            fileID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            data, resp := Client.GetFilePreview(fileID)
+  "/api/v4/files/{file_id}/link":
+    get:
+      tags:
+        - files
+      summary: Get a public file link
+      description: >
+        Gets a public link for a file that can be accessed without logging into
+        Mattermost.
+
+        ##### Permissions
+
+        Must have `read_channel` permission or be uploader of the file.
+      operationId: GetFileLink
+      parameters:
+        - name: file_id
+          in: path
+          description: The ID of the file to get a link for
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A publicly accessible link to the given file
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  link:
+                    type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            fileID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            data, resp := Client.GetFileLink(fileID)
+  "/api/v4/files/{file_id}/info":
+    get:
+      tags:
+        - files
+      summary: Get metadata for a file
+      description: |
+        Gets a file's info.
+        ##### Permissions
+        Must have `read_channel` permission or be uploader of the file.
+      operationId: GetFileInfo
+      parameters:
+        - name: file_id
+          in: path
+          description: The ID of the file info to get
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The stored metadata for the given file
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FileInfo"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            fileID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            info, resp := Client.GetFileInfo(fileID)
+  "/api/v4/files/{file_id}/public":
+    get:
+      tags:
+        - files
+      summary: Get a public file
+      description: |
+        ##### Permissions
+        No permissions required.
+      operationId: GetFilePublic
+      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":
+          description: Do not have appropriate permissions
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+          headers:
+            First-Inaccessible-File-Time:
+              schema:
+                type: integer
+              description: This header is included with the value "1" if the file is past the cloud's plan limit.
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
+  "/api/v4/teams/{team_id}/files/search":
+    post:
+      tags:
+        - teams
+        - files
+        - search
+      summary: Search files in a team
+      description: >
+        Search for files in a team based on file name, extention and file
+        content (if file content extraction is enabled and supported for the
+        files).
+
+        __Minimum server version__: 5.34
+
+        ##### Permissions
+
+        Must be authenticated and have the `view_team` permission.
+      operationId: SearchFiles
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+                - terms
+                - is_or_search
+              properties:
+                terms:
+                  type: string
+                  description: The search terms as inputed by the user. To search for files
+                    from a user include `from:someusername`, using a user's
+                    username. To search in a specific channel include
+                    `in:somechannel`, using the channel name (not the display
+                    name). To search for specific extensions included `ext:extension`.
+                is_or_search:
+                  type: boolean
+                  description: Set to true if an Or search should be performed vs an And
+                    search.
+                time_zone_offset:
+                  type: integer
+                  default: 0
+                  description: Offset from UTC of user timezone for date searches.
+                include_deleted_channels:
+                  type: boolean
+                  description: Set to true if deleted channels should be included in the
+                    search. (archived channels)
+                page:
+                  type: integer
+                  default: 0
+                  description: The page to select. (Only works with Elasticsearch)
+                per_page:
+                  type: integer
+                  default: 60
+                  description: The number of posts per page. (Only works with Elasticsearch)
+        description: The search terms and logic to use in the search.
+        required: true
+      responses:
+        "200":
+          description: Files list retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FileInfoList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+            teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
+
+            fileInfoList, resp := Client.SearchFiles(teamID, "filename", false)
+        - lang: curl
+          source: >
+            curl -X POST \
+              https://your-mattermost-url.com/api/v4/teams/zWEyrTZ7GZ22aBSfoX60iWryTY/files/search \
+              -H 'Authorization: Bearer frn8fu5rtpyc5m4xy6q3oj4yur' \
+              -H 'Content-Type: application/json' \
+              -d '{"terms": "filename", "is_or_search": false}'

api/v4/source/imports.yaml

@@ -0,0 +1,39 @@
+  "/api/v4/imports":
+    get:
+      tags:
+        - imports
+      summary: List import files
+      description: >
+        Lists all available import files.
+
+
+        __Minimum server version__: 5.31
+
+        ##### Permissions
+
+        Must have `manage_system` permissions.
+      operationId: ListImports
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+            imports, response := Client.ListImports()
+        - lang: Curl
+          source: |
+            curl 'http://localhost:8065/api/v4/imports' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'

api/v4/source/insights.yaml

@@ -0,0 +1,439 @@
+  /api/v4/teams/{team_id}/top/reactions:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top reactions for a team.
+      description: |
+        Get a list of the top reactions across all public and private channels (the user is a member of) for a given team.
+        ##### Permissions
+        Must have `view_team` permission for the team.
+      operationId: GetTopReactionsForTeam
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: reactions posted on the current day.
+            
+            - `7_day`: reactions posted in the last 7 days.
+            
+            - `28_day`: reactions posted in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Top reactions retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopReactionList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/users/me/top/reactions:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top reactions for a user.
+      description: |
+        Get a list of the top reactions across all public and private channels (the user is a member of) for a given user.
+        If no `team_id` is provided, this will also include reactions posted by the given user in direct and group messages.
+        ##### Permissions
+        Must be logged in as the user.
+      operationId: GetTopReactionsForUser
+      parameters:
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: reactions posted on the current day.
+            
+            - `7_day`: reactions posted in the last 7 days.
+            
+            - `28_day`: reactions posted in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+        - name: team_id
+          in: query
+          description: >
+            Team ID will scope the response to a given team and exclude direct and group messages.
+           
+            ##### Permissions
+            
+            Must have `view_team` permission for the team.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Top reactions retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopReactionList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/teams/{team_id}/top/channels:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top channels for a team.
+      description: |
+        Get a list of the top public and private channels (the user is a member of) for a given team.
+        ##### Permissions
+        Must have `view_team` permission for the team.
+      operationId: GetTopChannelsForTeam
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: channels with posts on the current day.
+            
+            - `7_day`: channels with posts in the last 7 days.
+            
+            - `28_day`: channels with posts in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Top channels retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopChannelList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/users/me/top/channels:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top channels for a user.
+      description: |
+        Get a list of the top public and private channels (the user is a member of) for a given user.
+        ##### Permissions
+        Must be logged in as the user.
+      operationId: GetTopChannelsForUser
+      parameters:
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: channels with posts on the current day.
+            
+            - `7_day`: channels with posts in the last 7 days.
+            
+            - `28_day`: channels with posts in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+        - name: team_id
+          in: query
+          description: >
+            Team ID will scope the response to a given team.
+
+            ##### Permissions
+           
+            Must have `view_team` permission for the team.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Top channels retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopChannelList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/teams/{team_id}/top/team_members:
+    get:
+      tags:
+        - insights
+      summary: Get a list of new team members.
+      description: |
+        Get a list of all of the new team members that have joined the given team during the given time period.
+        ##### Permissions
+        Must have `view_team` permission for the team.
+      operationId: GetNewTeamMembers
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: team members who joined during the current day.
+
+            - `7_day`: team members who joined in the last 7 days.
+
+            - `28_day`: team members who joined in the last 28 days.
+          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 items per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: New team members retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/NewTeamMembersList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/teams/{team_id}/top/threads:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top threads for a team.
+      description: |
+        Get a list of the top threads from public and private channels (the user is a member of) for a given team.
+        ##### Permissions
+        Must have `view_team` permission for the team.
+      operationId: GetTopThreadsForTeam
+      parameters:
+        - name: team_id
+          in: path
+          description: Team GUID
+          required: true
+          schema:
+            type: string
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: threads with activity on the current day.
+            
+            - `7_day`: threads with activity in the last 7 days.
+            
+            - `28_day`: threads with activity in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Top threads retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopThreadList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/users/me/top/threads:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top threads for a user.
+      description: |
+        Get a list of the top threads from public and private channels (the user is a member of and participating in the thread) for a given user.
+        ##### Permissions
+        Must be logged in as the user.
+      operationId: GetTopThreadsForUser
+      parameters:
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: threads with activity on the current day.
+            
+            - `7_day`: threads with activity in the last 7 days.
+            
+            - `28_day`: threads with activity in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+        - name: team_id
+          in: query
+          description: >
+            Team ID will scope the response to a given team.
+
+            ##### Permissions
+           
+            Must have `view_team` permission for the team.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Top threads retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopThreadList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/users/me/top/dms:
+    get:
+      tags:
+        - insights
+      summary: Get a list of the top dms for a user.
+      description: |
+        Get a list of the top dms for a given user.
+        ##### Permissions
+        Must be logged in as the user.
+      operationId: GetTopDMsForUser
+      parameters:
+        - name: time_range
+          in: query
+          description: >
+            Time range can be "today", "7_day", or "28_day".
+
+            - `today`: threads with activity on the current day.
+            
+            - `7_day`: threads with activity in the last 7 days.
+            
+            - `28_day`: threads with activity in the last 28 days.
+          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 items per page, up to a maximum of 200.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Top dms retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: "#/components/schemas/TopDMList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"

api/v4/source/introduction.yaml

@@ -0,0 +1,647 @@
+openapi: 3.0.0
+info:
+  description: >
+    There is also a work-in-progress [Postman API
+    reference](https://documenter.getpostman.com/view/4508214/RW8FERUn).
+  version: 4.0.0
+  title: Mattermost API Reference
+  termsOfService: https://about.mattermost.com/default-terms/
+  contact:
+    email: feedback@mattermost.com
+  x-logo:
+    url: https://mattermost.com/wp-content/uploads/2022/02/logoHorizontal.png
+    backgroundColor: "#FFFFFF"
+tags:
+  - name: introduction
+    description: >
+      The Mattermost Web Services API is used by Mattermost clients and third
+      party applications to interact with the server. [JavaScript and Golang
+      drivers for](/#tag/drivers) connecting to the APIs are also available.
+
+
+      ### Support
+
+
+      Mattermost core committers work with the community to keep the API documentation up-to-date.
+
+
+      If you have questions on API routes not listed in this reference, please [join the Mattermost community server](https://community.mattermost.com) to ask questions in the Developers channel, [or post questions to our Developer Discussion forum](https://forum.mattermost.org/c/dev).
+
+
+      [Bug reports](https://github.com/mattermost/mattermost-api-reference/issues) in the documentation or the API are also welcome, as are pull requests to fix the issues.
+
+
+      ### Contributing
+
+
+      When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. [Small changes](https://github.com/mattermost/mattermost-api-reference/commit/d574c0c1e95dc2228dc96663afd562f1305e3ece) and [larger changes](https://github.com/mattermost/mattermost-api-reference/commit/1ae3314f0935eebba8c885d8969dcad72f801501) are all welcome.
+
+
+      We also have [Help Wanted tickets](https://github.com/mattermost/mattermost-api-reference/issues) available for community members who would like to help others more easily use the APIs. We acknowledge everyone's contribution in the [release notes of our next version](https://docs.mattermost.com/administration/changelog.html#contributors).
+
+
+      The source code for this API reference is hosted at https://github.com/mattermost/mattermost-api-reference.
+  - name: schema
+    description: >
+      All API access is through HTTP(S) requests at
+      `your-mattermost-url.com/api/v4`. All request and response bodies are
+      `application/json`.
+
+
+      When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user.
+  - name: drivers
+    description: >
+      The easiest way to interact with the Mattermost Web Service API is through
+      a language specific driver.
+
+
+      #### Official Drivers
+
+      * [Mattermost JavaScript Driver](https://github.com/mattermost/mattermost-redux/blob/master/src/client/client4.ts)
+
+      * [Mattermost Golang Driver](https://github.com/mattermost/mattermost/blob/master/server/public/model/client4.go)
+
+
+      #### Community-built Drivers
+
+      * [PHP Driver](https://github.com/gnello/php-mattermost-driver) - built by [@gnello](https://github.com/gnello) and [@prixone](https://github.com/prixone)
+
+      * [Python Driver](https://github.com/Vaelor/python-mattermost-driver) - built by [@Vaelor](https://github.com/Vaelor)
+
+
+      For other community-built drivers and API wrappers, see [our app directory](https://mattermost.com/marketplace/).
+  - name: authentication
+    description: >
+      There are multiple ways to authenticate against the Mattermost API.
+
+
+      All examples assume there is a Mattermost instance running at http://localhost:8065.
+
+
+      #### Session Token
+
+
+      Make an HTTP POST to `your-mattermost-url.com/api/v4/users/login` with a JSON body indicating the user’s `login_id`, `password` and optionally the MFA `token`. The `login_id` can be an email, username or an AD/LDAP ID depending on the system's configuration.
+
+
+      ```
+
+      curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login
+
+      ```
+
+
+      NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below:
+
+
+      ```
+
+      curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login
+
+      ```
+
+
+      If successful, the response will contain a `Token` header and a user object in the body.
+
+
+      ```
+
+      HTTP/1.1 200 OK
+
+      Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
+
+      Token: hyr5dmb1mbb49c44qmx4whniso
+
+      X-Ratelimit-Limit: 10
+
+      X-Ratelimit-Remaining: 9
+
+      X-Ratelimit-Reset: 1
+
+      X-Request-Id: smda55ckcfy89b6tia58shk5fh
+
+      X-Version-Id: developer
+
+      Date: Fri, 11 Sep 2015 13:21:14 GMT
+
+      Content-Length: 657
+
+      Content-Type: application/json; charset=utf-8
+
+
+      {{user object as json}}
+
+      ```
+
+
+      Include the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method.
+
+
+      ```
+
+      curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me
+
+      ```
+
+
+      You should now be able to access the API as the user you logged in as.
+
+
+      #### Personal Access Tokens
+
+
+      Using [personal access tokens](https://docs.mattermost.com/developer/personal-access-tokens.html) is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.
+
+
+      Just like session tokens, include the personal access token as part of the `Authorization` header in your requests using the `Bearer` method. Assuming our personal access token is `9xuqwrwgstrb3mzrxb83nb357a`, we could use it as shown below.
+
+
+      ```
+
+      curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me
+
+      ```
+
+
+      #### OAuth 2.0
+
+
+      Mattermost has the ability to act as an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) service provider.
+
+
+      The official documentation for [using your Mattermost server as an OAuth 2.0 service provider can be found here.](https://docs.mattermost.com/developer/oauth-2-0-applications.html)
+
+
+      For an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the [Mattermost-Zapier integration documentation](https://docs.mattermost.com/integrations/zapier.html#register-zapier-as-an-oauth-2-0-application).
+  - name: errors
+    description: >
+      All errors will return an appropriate HTTP response code along with the
+      following JSON body:
+
+      ```
+
+      {
+          "id": "the.error.id",
+          "message": "Something went wrong", // the reason for the error
+          "request_id": "", // the ID of the request
+          "status_code": 0, // the HTTP status code
+          "is_oauth": false // whether the error is OAuth specific
+      }
+
+      ```
+  - name: rate limiting
+    description: >
+      Whenever you make an HTTP request to the Mattermost API you might notice
+      the following headers included in the response:
+
+      ```
+
+      X-Ratelimit-Limit: 10
+
+      X-Ratelimit-Remaining: 9
+
+      X-Ratelimit-Reset: 1441983590
+
+      ```
+
+
+      These headers are telling you your current rate limit status.
+
+
+      | Header | Description |
+
+      | ------ | ----------- |
+
+      | X-Ratelimit-Limit | The maximum number of requests you can make per second. |
+
+      | X-Ratelimit-Remaining | The number of requests remaining in the current window. |
+
+      | X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. |
+
+
+      If you exceed your rate limit for a window you will receive the following error in the body of the response:
+
+
+      ```
+
+      HTTP/1.1 429 Too Many Requests
+
+      Date: Tue, 10 Sep 2015 11:20:28 GMT
+
+      X-RateLimit-Limit: 10
+
+      X-RateLimit-Remaining: 0
+
+      X-RateLimit-Reset: 1
+
+
+      limit exceeded
+
+      ```
+  - name: WebSocket
+    description: >
+      In addition to the HTTP RESTful web service, Mattermost also offers a
+      WebSocket event delivery system and some API functionality.
+
+
+      To connect to the WebSocket follow the standard opening handshake as [defined by the RFC specification](https://tools.ietf.org/html/rfc6455#section-1.3) to the `/api/v4/websocket` endpoint of Mattermost.
+
+
+      #### Authentication
+
+
+      The Mattermost WebSocket can be authenticated using [the standard API authentication methods](/#tag/authentication) (by a cookie or with an explicit Authorization header) or through an authentication challenge. If you're authenticating from a browser and have logged in with the Mattermost API, your authentication cookie should already be set. This is how the Mattermost webapp authenticates with the WebSocket.
+
+
+      To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:
+
+
+      ```
+
+      {
+        "seq": 1,
+        "action": "authentication_challenge",
+        "data": {
+          "token": "mattermosttokengoeshere"
+        }
+      }
+
+      ```
+
+
+      If successful, you will receive a standard OK response over the WebSocket connection:
+
+
+      ```
+
+      {
+        "status": "OK",
+        "seq_reply": 1
+      }
+
+      ```
+
+
+      Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection.
+
+
+      #### 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.
+
+
+      Events on the WebSocket will have the form:
+
+
+      ```
+
+      {
+        "event": "hello",
+        "data": {
+          "server_version": "3.6.0.1451.1c38da627ebb4e3635677db6939e9195"
+        },
+        "broadcast":{
+          "omit_users": null,
+          "user_id": "ay5sq51sebfh58ktrce5ijtcwy",
+          "channel_id": "",
+          "team_id": ""
+        },
+        "seq": 0
+      }
+
+      ```
+
+
+      The `event` field indicates the event type, `data` contains any data relevant to the event and `broadcast` contains information about who the event was sent to. For example, the above example has `user_id` set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The `omit_users` field can contain an array of user IDs that were specifically omitted from receiving the event.
+
+
+      The list of Mattermost WebSocket events are:
+
+      - added_to_team
+
+      - authentication_challenge
+
+      - channel_converted
+
+      - channel_created
+
+      - channel_deleted
+
+      - channel_member_updated
+
+      - channel_updated
+
+      - channel_viewed
+
+      - config_changed
+
+      - delete_team
+
+      - direct_added
+
+      - emoji_added
+
+      - ephemeral_message
+
+      - group_added
+
+      - hello
+
+      - leave_team
+
+      - license_changed
+
+      - memberrole_updated
+
+      - new_user
+
+      - plugin_disabled
+
+      - plugin_enabled
+
+      - plugin_statuses_changed
+
+      - post_deleted
+
+      - post_edited
+
+      - post_unread
+
+      - posted
+
+      - preference_changed
+
+      - preferences_changed
+
+      - preferences_deleted
+
+      - reaction_added
+
+      - reaction_removed
+
+      - response
+
+      - role_updated
+
+      - status_change
+
+      - typing
+
+      - update_team
+
+      - user_added
+
+      - user_removed
+
+      - user_role_updated
+
+      - user_updated
+
+      - dialog_opened
+
+      - thread_updated
+
+      - thread_follow_changed
+
+      - thread_read_changed
+
+
+      #### WebSocket API
+
+
+      Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:
+
+
+      ```
+
+      {
+        "action": "user_typing",
+        "seq": 2,
+        "data": {
+          "channel_id": "nhze199c4j87ped4wannrjdt9c",
+          "parent_id": ""
+        }
+      }
+
+      ```
+
+
+      This is an example of making a `user_typing` request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The `action` field indicates what is being requested, and performs a similar duty as the route in a HTTP API. The `data` field is used to add any additional data along with the request. The server supports binary websocket messages as well in case the client has such a requirement.
+
+
+      The `seq` or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be:
+
+
+      ```
+
+      {
+        "status": "OK",
+        "seq_reply": 2
+      }
+
+      ```
+
+
+      Notice `seq_reply` is 2, matching the `seq` of the original request. Using this a client can distinguish which request the response is meant for.
+
+
+      If there was any information to respond with, it would be encapsulated in a `data` field.
+
+
+      In the case of an error, the response would be:
+
+
+      ```
+
+      {
+        "status": "FAIL",
+        "seq_reply": 2,
+        "error": {
+          "id": "some.error.id.here",
+          "message": "Some error message here"
+        }
+      }
+
+      ```
+
+
+      The list of WebSocket API actions is:
+
+      - user_typing
+
+      - get_statuses
+
+      - get_statuses_by_ids
+
+
+      To see how these actions work, please refer to either the [Golang WebSocket driver](https://github.com/mattermost/mattermost-server/blob/master/model/websocket_client.go) or our [JavaScript WebSocket driver](https://github.com/mattermost/mattermost-redux/blob/master/src/client/websocket_client.ts).
+  - name: APIv3 Deprecation
+    description: >
+      Since Mattermost 4.6 released on January 16, 2018, API v3 has no longer
+      been supported and it will be removed in Mattermost Server v5.0 on June
+      16, 2018. Follow these simple steps to migrate your integrations and apps
+      to API v4. Otherwise your integrations may break once you upgrade to
+      Mattermost 5.0
+
+
+      1. Set your server's log level to `DEBUG` in **System Console > General > Logging > File Log Level** to print detailed logs for API requests.
+
+      2. In **System Console > Logs**, search for requests hitting `/api/v3/` endpoints. Any requests hitting these endpoints are from integrations that should be migrated to API v4.
+        - For in-house or self-built integrations, update them to use v4 with the help of [this API reference](https://api.mattermost.com). Most v3 endpoints have direct counterparts in v4 and should be migrated easily.
+        - For third-party integrations, visit their homepage (on GitHub, GitLab, etc.). Check if they already have a version that uses the Mattermost v4 API. If they do not, consider opening an issue asking them if support is planned.
+      3. Once all integrations have been migrated to API v4, review the server logs with log level set to `DEBUG`. Confirm no requests hit `/api/v3/` endpoints.
+
+      4. Set **Allow use of API v3 endpoints** to `false` in **System Console > General > Configuration**, or set `EnableAPIv3` to `false` in `config.json`. This setting disables API v3 on your server. Any time a v3 endpoint is used, an error is logged in **System Console > Logs**.
+
+      5. Set your server's log level back to `ERROR`. Use the error logs to help track down any remaining uses of API v3.
+
+
+      Below are the major changes made between v3 and v4:
+
+
+      1. Endpoint URLs only require team IDs when necessary. For example, getting a channel by ID no longer requires a team ID in v4.
+
+      2. Collection endpoints now generally return lists and include paging as part of the query string.
+
+      3. User ID is now included in most user endpoints. This allows admins to modify other users through v4 endpoints.
+
+
+      If you have any questions about the API v3 deprecation, or about migrating from v3 to v4, [join our daily build server at community.mattermost.com](https://community.mattermost.com) and ask questions in the [APIv4 channel](https://community.mattermost.com/core/channels/apiv4).
+  - name: users
+    description: >
+      Endpoints for creating, getting and interacting with users.
+
+
+      When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user.
+  - name: bots
+    description: Endpoints for creating, getting and updating bot users.
+  - name: teams
+    description: Endpoints for creating, getting and interacting with teams.
+  - name: channels
+    description: Endpoints for creating, getting and interacting with channels.
+  - name: posts
+    description: Endpoints for creating, getting and interacting with posts.
+  - name: files
+    description: Endpoints for uploading and interacting with files.
+  - name: uploads
+    description: Endpoints for creating and performing file uploads.
+  - name: preferences
+    description: Endpoints for saving and modifying user preferences.
+  - name: status
+    description: Endpoints for getting and updating user statuses.
+  - name: emoji
+    description: Endpoints for creating, getting and interacting with emojis.
+  - name: reactions
+    description: Endpoints for creating, getting and removing emoji reactions.
+  - name: webhooks
+    description: Endpoints for creating, getting and updating webhooks.
+  - name: commands
+    description: Endpoints for creating, getting and updating slash commands.
+  - name: OpenGraph
+    description: Endpoint for getting Open Graph metadata.
+  - name: system
+    description: General endpoints for interacting with the server, such as configuration and logging.
+  - name: brand
+    description:
+      Endpoints related to custom branding and white-labeling. See [our branding
+      documentation](https://docs.mattermost.com/administration/branding.html)
+      for more information.
+  - name: OAuth
+    description:
+      Endpoints for configuring and interacting with Mattermost as an OAuth 2.0
+      service provider.
+  - name: SAML
+    description: Endpoints for configuring and interacting with SAML.
+  - name: LDAP
+    description: Endpoints for configuring and interacting with LDAP.
+  - name: groups
+    description: Endpoints related to LDAP groups.
+  - name: compliance
+    description: Endpoints for creating, getting and downloading compliance reports.
+  - name: cluster
+    description: Endpoints for configuring and interacting with high availability clusters.
+  - name: elasticsearch
+    description: Endpoints for configuring and interacting with Elasticsearch.
+  - name: data retention
+    description: Endpoint for getting data retention policy settings.
+  - name: jobs
+    description:
+      Endpoints related to various background jobs that can be run by the server
+      or separately by job servers.
+  - name: plugins
+    description: Endpoints related to uploading and managing plugins.
+  - name: roles
+    description: Endpoints for creating, getting and updating roles.
+  - name: schemes
+    description: Endpoints for creating, getting and updating and deleting schemes.
+  - name: integration_actions
+    description: Endpoints for interactive actions for use by integrations.
+  - name: shared channels
+    description: Endpoints for getting information about shared channels.
+  - name: insights
+    description: Endpoints for getting insights into teams and users.
+  - name: terms of service
+    description: Endpoints for getting and updating custom terms of service.
+  - name: imports
+    description: Endpoints related to import files.
+  - name: exports
+    description: Endpoints related to export files.
+x-tagGroups:
+  - name: Overview
+    tags:
+      - introduction
+      - schema
+      - APIv3 Deprecation
+  - name: Standard Features
+    tags:
+      - drivers
+      - authentication
+      - errors
+      - rate limiting
+      - WebSocket
+  - name: Endpoints
+    tags:
+      - users
+      - bots
+      - teams
+      - channels
+      - posts
+      - threads
+      - files
+      - uploads
+      - preferences
+      - status
+      - emoji
+      - reactions
+      - webhooks
+      - commands
+      - OpenGraph
+      - system
+      - brand
+      - OAuth
+      - SAML
+      - LDAP
+      - groups
+      - compliance
+      - cluster
+      - cloud
+      - elasticsearch
+      - bleve
+      - data retention
+      - jobs
+      - plugins
+      - roles
+      - schemes
+      - integration_actions
+      - shared channels
+      - insights
+      - terms of service
+      - imports
+      - permissions
+      - exports
+      - usage
+servers:
+  - url: http://your-mattermost-url.com
+  - url: https://your-mattermost-url.com
+paths:

api/v4/source/jobs.yaml

@@ -0,0 +1,225 @@
+  /api/v4/jobs:
+    get:
+      tags:
+        - jobs
+      summary: Get the jobs.
+      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 `manage_jobs` permission.
+      operationId: GetJobs
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of jobs per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Job list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    post:
+      tags:
+        - jobs
+      summary: Create a new job.
+      description: |
+        Create a new job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Must have `manage_jobs` permission.
+      operationId: CreateJob
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - type
+              properties:
+                type:
+                  type: string
+                  description: The type of job to create
+                data:
+                  type: object
+                  description: An object containing any additional data required for this
+                    job type
+        description: Job object to be created
+        required: true
+      responses:
+        "201":
+          description: Job creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/jobs/{job_id}":
+    get:
+      tags:
+        - jobs
+      summary: Get a job.
+      description: |
+        Gets a single job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Must have `manage_jobs` permission.
+      operationId: GetJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/jobs/{job_id}/download":
+    get:
+      tags:
+        - jobs
+      summary: Download the results of a job.
+      description: |
+        Download the result of a single job.
+        __Minimum server version: 5.28__
+        ##### Permissions
+        Must have `manage_jobs` permission.
+      operationId: DownloadJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          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"
+  "/api/v4/jobs/{job_id}/cancel":
+    post:
+      tags:
+        - jobs
+      summary: Cancel a job.
+      description: |
+        Cancel a job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Must have `manage_jobs` permission.
+      operationId: CancelJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job canceled successfully
+          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"
+  "/api/v4/jobs/type/{type}":
+    get:
+      tags:
+        - jobs
+      summary: Get the jobs of the given type.
+      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 `manage_jobs` permission.
+      operationId: GetJobsByType
+      parameters:
+        - name: type
+          in: path
+          description: Job type
+          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 jobs per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Job list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"

api/v4/source/ldap.yaml

@@ -0,0 +1,327 @@
+  /api/v4/ldap/sync:
+    post:
+      tags:
+        - LDAP
+      summary: Sync with LDAP
+      description: >
+        Synchronize any user attribute changes in the configured AD/LDAP server
+        with Mattermost.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: SyncLdap
+      responses:
+        "200":
+          description: LDAP sync successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/ldap/test:
+    post:
+      tags:
+        - LDAP
+      summary: Test LDAP configuration
+      description: >
+        Test the current AD/LDAP configuration to see if the AD/LDAP server can
+        be contacted successfully.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: TestLdap
+      responses:
+        "200":
+          description: LDAP test successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/ldap/groups:
+    get:
+      tags:
+        - ldap
+      summary: Returns a list of LDAP groups
+      description: >
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.11
+      operationId: GetLdapGroups
+      parameters:
+        - name: q
+          in: query
+          description: Search term
+          required: false
+          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 users per page. There is a maximum limit of 200 users
+            per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: LDAP group page retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/LDAPGroupsPaged"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v4/ldap/groups/{remote_id}/link:
+    post:
+      tags:
+        - ldap
+      summary: Link a LDAP group
+      description: >
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.11
+      operationId: LinkLdapGroup
+      parameters:
+        - name: remote_id
+          in: path
+          description: Group GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "201":
+          description: LDAP group successfully linked
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    delete:
+      tags:
+        - groups
+      summary: Delete a link for LDAP group
+      description: >
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.11
+      operationId: UnlinkLdapGroup
+      parameters:
+        - name: remote_id
+          in: path
+          description: Group GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successfully deleted ldap group link
+          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/ldap/migrateid:
+    post:
+      tags:
+        - LDAP
+      summary: Migrate Id LDAP
+      description: >
+        Migrate LDAP IdAttribute to new value.
+  
+        ##### Permissions
+  
+        Must have `manage_system` permission.
+  
+        __Minimum server version__: 5.26
+      operationId: MigrateIdLdap
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - toAttribute
+              properties:
+                toAttribute:
+                  description: New IdAttribute value
+                  type: string
+        required: true
+      responses:
+        "200":
+          description: Migration successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "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/ldap/certificate/public:
+    post:
+      tags:
+        - LDAP
+      summary: Upload public certificate
+      description: >
+        Upload the public certificate to be used for TLS verification. The server will pick a hard-coded filename for the
+        PublicCertificateFile setting in your `config.json`.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: UploadLdapPublicCertificate
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                certificate:
+                  description: The public certificate file
+                  type: string
+                  format: binary
+              required:
+                - certificate
+      responses:
+        "200":
+          description: LDAP certificate upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - LDAP
+      summary: Remove public certificate
+      description: >
+        Delete the current public certificate being used for TLS verification.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: DeleteLdapPublicCertificate
+      responses:
+        "200":
+          description: LDAP certificate delete 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/ldap/certificate/private:
+    post:
+      tags:
+        - LDAP
+      summary: Upload private key
+      description: >
+        Upload the private key to be used for TLS verification. The server will pick a hard-coded filename for the
+        PrivateKeyFile setting in your `config.json`.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: UploadLdapPrivateCertificate
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                certificate:
+                  description: The private key file
+                  type: string
+                  format: binary
+              required:
+                - certificate
+      responses:
+        "200":
+          description: LDAP certificate upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - LDAP
+      summary: Remove private key
+      description: >
+        Delete the current private key being used with your TLS verification.
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: DeleteLdapPrivateCertificate
+      responses:
+        "200":
+          description: LDAP certificate delete 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/source/oauth.yaml

@@ -0,0 +1,387 @@
+  /api/v4/oauth/apps:
+    post:
+      tags:
+        - OAuth
+      summary: Register OAuth app
+      description: >
+        Register an OAuth 2.0 client application with Mattermost as the service
+        provider.
+
+        ##### Permissions
+
+        Must have `manage_oauth` permission.
+      operationId: CreateOAuthApp
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - description
+                - callback_urls
+                - homepage
+              properties:
+                name:
+                  type: string
+                  description: The name of the client application
+                description:
+                  type: string
+                  description: A short description of the application
+                icon_url:
+                  type: string
+                  description: A URL to an icon to display with the application
+                callback_urls:
+                  type: array
+                  items:
+                    type: string
+                  description: A list of callback URLs for the appliation
+                homepage:
+                  type: string
+                  description: A link to the website of the application
+                is_trusted:
+                  type: boolean
+                  description: Set this to `true` to skip asking users for permission
+        description: OAuth application to register
+        required: true
+      responses:
+        "201":
+          description: App registration successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OAuthApp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    get:
+      tags:
+        - OAuth
+      summary: Get OAuth apps
+      description: >
+        Get a page of OAuth 2.0 client applications registered with Mattermost.
+
+        ##### Permissions
+
+        With `manage_oauth` permission, the apps registered by the logged in user are returned. With `manage_system_wide_oauth` permission, all apps regardless of creator are returned.
+      operationId: GetOAuthApps
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of apps per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: OAuthApp list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/OAuthApp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/oauth/apps/{app_id}":
+    get:
+      tags:
+        - OAuth
+      summary: Get an OAuth app
+      description: >
+        Get an OAuth 2.0 client application registered with Mattermost.
+
+        ##### Permissions
+
+        If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.
+      operationId: GetOAuthApp
+      parameters:
+        - name: app_id
+          in: path
+          description: Application client id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: App retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OAuthApp"
+        "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"
+    put:
+      tags:
+        - OAuth
+      summary: Update an OAuth app
+      description: >
+        Update an OAuth 2.0 client application based on OAuth struct.
+
+        ##### Permissions
+
+        If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.
+      operationId: UpdateOAuthApp
+      parameters:
+        - name: app_id
+          in: path
+          description: Application client id
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+                - name
+                - description
+                - callback_urls
+                - homepage
+              properties:
+                id:
+                  type: string
+                  description: The id of the client application
+                name:
+                  type: string
+                  description: The name of the client application
+                description:
+                  type: string
+                  description: A short description of the application
+                icon_url:
+                  type: string
+                  description: A URL to an icon to display with the application
+                callback_urls:
+                  type: array
+                  items:
+                    type: string
+                  description: A list of callback URLs for the appliation
+                homepage:
+                  type: string
+                  description: A link to the website of the application
+                is_trusted:
+                  type: boolean
+                  description: Set this to `true` to skip asking users for permission. It
+                    will be set to false if value is not provided.
+        description: OAuth application to update
+        required: true
+      responses:
+        "200":
+          description: App update successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OAuthApp"
+        "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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            appToUpdate := &model.OAuthApp{
+              Id:           <APP ID>,
+              Name:         <APP NAME>,
+              Description:  <APP DESCRIPTION>,
+              IconURL:      <URL TO APP ICON>,
+              CallbackUrls: [<CALLBACK URL1>, <CALLBACK URL2>],
+              Homepage:     <URL TO APP HOMEPAGE>,
+              IsTrusted:    <BOOLEAN>
+            }
+
+            // UpdateOAuthApp
+            updatedApp, resp := Client.UpdateOAuthApp(appToUpdate)
+    delete:
+      tags:
+        - OAuth
+      summary: Delete an OAuth app
+      description: >
+        Delete and unregister an OAuth 2.0 client application 
+
+        ##### Permissions
+
+        If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.
+      operationId: DeleteOAuthApp
+      parameters:
+        - name: app_id
+          in: path
+          description: Application client id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: App 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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/oauth/apps/{app_id}/regen_secret":
+    post:
+      tags:
+        - OAuth
+      summary: Regenerate OAuth app secret
+      description: >
+        Regenerate the client secret for an OAuth 2.0 client application
+        registered with Mattermost.
+
+        ##### Permissions
+
+        If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.
+      operationId: RegenerateOAuthAppSecret
+      parameters:
+        - name: app_id
+          in: path
+          description: Application client id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Secret regeneration successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OAuthApp"
+        "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/oauth/apps/{app_id}/info":
+    get:
+      tags:
+        - OAuth
+      summary: Get info on an OAuth app
+      description: >
+        Get public information about an OAuth 2.0 client application registered
+        with Mattermost. The application's client secret will be blanked out.
+
+        ##### Permissions
+
+        Must be authenticated.
+      operationId: GetOAuthAppInfo
+      parameters:
+        - name: app_id
+          in: path
+          description: Application client id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: App retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OAuthApp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/users/{user_id}/oauth/apps/authorized":
+    get:
+      tags:
+        - OAuth
+      summary: Get authorized OAuth apps
+      description: >
+        Get a page of OAuth 2.0 client applications authorized to access a
+        user's account.
+
+        ##### Permissions
+
+        Must be authenticated as the user or have `edit_other_users` permission.
+      operationId: GetAuthorizedOAuthAppsForUser
+      parameters:
+        - name: user_id
+          in: path
+          description: User 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 apps per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: OAuthApp list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/OAuthApp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/opengraph.yaml

@@ -0,0 +1,38 @@
+  /api/v4/opengraph:
+    post:
+      tags:
+        - OpenGraph
+      summary: Get open graph metadata for url
+      description: >
+        Get Open Graph Metadata for a specif URL. Use the Open Graph protocol to
+        get some generic metadata about a URL. Used for creating link previews.
+
+
+        __Minimum server version__: 3.10
+
+
+        ##### Permissions
+
+        No permission required but must be logged in.
+      operationId: OpenGraph
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - url
+              properties:
+                url:
+                  type: string
+                  description: The URL to get Open Graph Metadata.
+        required: true
+      responses:
+        "200":
+          description: Open Graph retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OpenGraph"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/permissions.yaml

@@ -0,0 +1,32 @@
+  /api/v4/permissions/ancillary:
+    get:
+      tags:
+        - permissions
+      summary: Return all system console subsection ancillary permissions
+      description: >
+        Returns all the ancillary permissions for the corresponding system console
+        subsection permissions appended to the requested permission subsections.
+
+
+        __Minimum server version__: 5.35
+      operationId: GetAncillaryPermissions
+      parameters:
+        - name: subsection_permissions
+          in: query
+          description: >
+            The subsection permissions to return the ancillary permissions for.
+            These values are comma seperated.
+            Ex. subsection_permissions=sysconsole_read_reporting_site_statistics,sysconsole_write_reporting_site_statistics,sysconsole_write_user_management_channels
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successfully returned all ancillary and requested permissions
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+        "400":
+          $ref: '#/components/responses/BadRequest'

api/v4/source/plugins.yaml

@@ -0,0 +1,616 @@
+  /api/v4/plugins:
+    post:
+      tags:
+        - plugins
+      summary: Upload plugin
+      description: >
+        Upload a plugin that is contained within a compressed .tar.gz file.
+        Plugins and plugin uploads must be enabled in the server's config
+        settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 4.4
+      operationId: UploadPlugin
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                plugin:
+                  description: The plugin image to be uploaded
+                  type: string
+                  format: binary
+                force:
+                  description: Set to 'true' to overwrite a previously installed plugin
+                    with the same ID, if any
+                  type: string
+              required:
+                - plugin
+      responses:
+        "201":
+          description: Plugin upload 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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import (
+              "bytes"
+              "io/ioutil"
+              "log"
+
+              "github.com/mattermost/mattermost-server/v5/model"
+            )
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+
+            tarData, err := ioutil.ReadFile("plugin.tar.gz")
+
+            if err != nil {
+              log.Fatal("error while reading file")
+            }
+
+
+            // Not forced
+
+            manifest, resp := Client.UploadPlugin(bytes.NewReader(tarData))
+
+
+            // Forced
+
+            manifest, resp := Client.UploadPluginForced(bytes.NewReader(tarData))
+    get:
+      tags:
+        - plugins
+      summary: Get plugins
+      description: >
+        Get a list of inactive and a list of active plugin manifests. Plugins
+        must be enabled in the server's config settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 4.4
+      operationId: GetPlugins
+      responses:
+        "200":
+          description: Plugins retrieval successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  active:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/PluginManifest"
+                  inactive:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/PluginManifest"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            pluginsResp, resp := Client.GetPlugins()
+  /api/v4/plugins/install_from_url:
+    post:
+      tags:
+        - plugins
+      summary: Install plugin from url
+      description: >
+        Supply a URL to a plugin compressed in a .tar.gz file. Plugins must be
+        enabled in the server's config settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 5.14
+      operationId: InstallPluginFromUrl
+      parameters:
+        - name: plugin_download_url
+          in: query
+          description: URL used to download the plugin
+          required: true
+          schema:
+            type: string
+        - name: force
+          in: query
+          description: Set to 'true' to overwrite a previously installed plugin with the
+            same ID, if any
+          required: false
+          schema:
+            type: string
+      responses:
+        "201":
+          description: Plugin install successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import (
+              "github.com/mattermost/mattermost-server/v5/model"
+            )
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            url := "https://mysite.com/my-plugin.tar.gz"
+
+            // Not forced
+            manifest, resp := Client.InstallPluginFromUrl(url, false)
+
+            // Forced
+            manifest, resp := Client.InstallPluginFromUrl(url, true)
+  "/api/v4/plugins/{plugin_id}":
+    delete:
+      tags:
+        - plugins
+      summary: Remove plugin
+      description: >
+        Remove the plugin with the provided ID from the server. All plugin files
+        are deleted. Plugins must be enabled in the server's config settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 4.4
+      operationId: RemovePlugin
+      parameters:
+        - name: plugin_id
+          description: Id of the plugin to be removed
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Plugin removed successfully
+          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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            pluginID := "com.mattermost.demo-plugin"
+
+            ok, resp = Client.RemovePlugin(pluginID)
+  "/api/v4/plugins/{plugin_id}/enable":
+    post:
+      tags:
+        - plugins
+      summary: Enable plugin
+      description: >
+        Enable a previously uploaded plugin. Plugins must be enabled in the
+        server's config settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 4.4
+      operationId: EnablePlugin
+      parameters:
+        - name: plugin_id
+          description: Id of the plugin to be enabled
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Plugin enabled successfully
+          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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            pluginID := "com.mattermost.demo-plugin"
+
+            ok, resp = Client.EnablePlugin(pluginID)
+  "/api/v4/plugins/{plugin_id}/disable":
+    post:
+      tags:
+        - plugins
+      summary: Disable plugin
+      description: >
+        Disable a previously enabled plugin. Plugins must be enabled in the
+        server's config settings.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 4.4
+      operationId: DisablePlugin
+      parameters:
+        - name: plugin_id
+          description: Id of the plugin to be disabled
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Plugin disabled successfully
+          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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            pluginID := "com.mattermost.demo-plugin"
+
+            ok, resp = Client.DisablePlugin(pluginID)
+  /api/v4/plugins/webapp:
+    get:
+      tags:
+        - plugins
+      summary: Get webapp plugins
+      description: |
+        Get a list of web app plugins installed and activated on the server.
+
+        ##### Permissions
+        No permissions required.
+
+        __Minimum server version__: 4.4
+      operationId: GetWebappPlugins
+      responses:
+        "200":
+          description: Plugin deactivated successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PluginManifestWebapp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            manifests, resp := Client.GetWebappPlugins()
+  /api/v4/plugins/statuses:
+    get:
+      tags:
+        - plugins
+      summary: Get plugins status
+      description: |
+        Returns the status for plugins installed anywhere in the cluster
+
+        ##### Permissions
+        No permissions required.
+
+        __Minimum server version__: 4.4
+      operationId: GetPluginStatuses
+      responses:
+        "200":
+          description: Plugin status retreived successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PluginStatus"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            manifests, resp := Client.GetPluginStatuses()
+  /api/v4/plugins/marketplace:
+    post:
+      tags:
+        - plugins
+      summary: Installs a marketplace plugin
+      description: |
+        Installs a plugin listed in the marketplace server.
+
+        ##### Permissions
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.16
+      operationId: InstallMarketplacePlugin
+      requestBody:
+        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.
+        description: The metadata identifying the plugin to install.
+        required: true
+      responses:
+        "200":
+          description: Plugin installed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PluginManifest"
+        "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"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            plugin := &model.InstallMarketplacePluginRequest{
+              Id: "antivirus",
+            }
+
+            ok, resp = Client.InstallMarketplacePlugin(plugin)
+    get:
+      tags:
+        - plugins
+      summary: Gets all the marketplace plugins
+      description: >
+        Gets all plugins from the marketplace server, merging data from locally
+        installed plugins as well as prepackaged plugins shipped with the
+        server.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 5.16
+      operationId: GetMarketplacePlugins
+      parameters:
+        - name: page
+          in: query
+          description: Page number to be fetched. (not yet implemented)
+          required: false
+          schema:
+            type: integer
+        - name: per_page
+          in: query
+          description: Number of item per page. (not yet implemented)
+          required: false
+          schema:
+            type: integer
+        - name: filter
+          in: query
+          description: Set to filter plugins by ID, name, or description.
+          required: false
+          schema:
+            type: string
+        - name: server_version
+          in: query
+          description: Set to filter minimum plugin server version. (not yet implemented)
+          required: false
+          schema:
+            type: string
+        - name: local_only
+          in: query
+          description: Set true to only retrieve local plugins.
+          required: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Plugins retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/MarketplacePlugin"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            filter := &model.MarketplacePluginFilter{
+              Page: 1,
+              PerPage: 10,
+              Filter: "antivirus",
+              ServerVersion: "0.1.2",
+              LocalOnly: true,
+            }
+
+            ok, resp = Client.GetMarketplacePlugins(filter)
+  /api/v4/plugins/marketplace/first_admin_visit:
+    get:
+      tags:
+        - plugins
+      summary: Get if the Plugin Marketplace has been visited by at least an admin.
+      description: |
+        Retrieves the status that specifies that at least one System Admin has visited the in-product Plugin Marketplace.
+        __Minimum server version: 5.33__
+        ##### Permissions
+        Must have `manage_system` permissions.
+      operationId: GetMarketplaceVisitedByAdmin
+      responses:
+        "200":
+          description: Retrieves the system-level status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/System"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    post:
+      tags:
+        - system
+      summary: Stores that the Plugin Marketplace has been visited by at least an admin.
+      description: |
+        Stores the system-level status that specifies that at least an admin has visited the in-product Plugin Marketplace.
+        __Minimum server version: 5.33__
+        ##### Permissions
+        Must have `manage_system` permissions.
+      operationId: UpdateMarketplaceVisitedByAdmin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/System"
+        required: true
+      responses:
+        "200":
+          description: setting has been successfully set
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"

api/v4/source/preferences.yaml

@@ -0,0 +1,202 @@
+  "/api/v4/users/{user_id}/preferences":
+    get:
+      tags:
+        - preferences
+      summary: Get the user's preferences
+      description: >
+        Get a list of the user's preferences.
+
+        ##### Permissions
+
+        Must be logged in as the user being updated or have the `edit_other_users` permission.
+      operationId: GetPreferences
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: User preferences retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Preference"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    put:
+      tags:
+        - preferences
+      summary: Save the user's preferences
+      description: >
+        Save a list of the user's preferences.
+
+        ##### Permissions
+
+        Must be logged in as the user being updated or have the `edit_other_users` permission.
+      operationId: UpdatePreferences
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: List of preference objects
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/Preference'
+      responses:
+        "200":
+          description: User preferences saved 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"
+  "/api/v4/users/{user_id}/preferences/delete":
+    post:
+      tags:
+        - preferences
+      summary: Delete user's preferences
+      description: >
+        Delete a list of the user's preferences.
+
+        ##### Permissions
+
+        Must be logged in as the user being updated or have the `edit_other_users` permission.
+      operationId: DeletePreferences
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: List of preference objects
+        required: true
+        content:
+          application/json:
+            schema:            
+              type: array
+              items:
+                $ref: '#/components/schemas/Preference'
+      responses:
+        "200":
+          description: User preferences saved 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/users/{user_id}/preferences/{category}":
+    get:
+      tags:
+        - preferences
+      summary: List a user's preferences by category
+      description: >
+        Lists the current user's stored preferences in the given category.
+
+        ##### Permissions
+
+        Must be logged in as the user being updated or have the `edit_other_users` permission.
+      operationId: GetPreferencesByCategory
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+        - name: category
+          in: path
+          description: The category of a group of preferences
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A list of all of the current user's preferences in the given category
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Preference"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/users/{user_id}/preferences/{category}/name/{preference_name}":
+    get:
+      tags:
+        - preferences
+      summary: Get a specific user preference
+      description: >
+        Gets a single preference for the current user with the given category
+        and name.
+
+        ##### Permissions
+
+        Must be logged in as the user being updated or have the `edit_other_users` permission.
+      operationId: GetPreferencesByCategoryByName
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+        - name: category
+          in: path
+          description: The category of a group of preferences
+          required: true
+          schema:
+            type: string
+        - name: preference_name
+          in: path
+          description: The name of the preference
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: >
+            A single preference for the current user in the current categorylist
+            of all of the current user's preferences in the given category.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Preference"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"

api/v4/source/reactions.yaml

@@ -0,0 +1,137 @@
+  /api/v4/reactions:
+    post:
+      tags:
+        - reactions
+      summary: Create a reaction
+      description: |
+        Create a reaction.
+        ##### Permissions
+        Must have `read_channel` permission for the channel the post is in.
+      operationId: SaveReaction
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Reaction"
+        description: The user's reaction with its post_id, user_id, and emoji_name fields
+          set
+        required: true
+      responses:
+        "201":
+          description: Reaction creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Reaction"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/posts/{post_id}/reactions":
+    get:
+      tags:
+        - reactions
+      summary: Get a list of reactions to a post
+      description: |
+        Get a list of reactions made by all users to a given post.
+        ##### Permissions
+        Must have `read_channel` permission for the channel the post is in.
+      operationId: GetReactions
+      parameters:
+        - name: post_id
+          in: path
+          description: ID of a post
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: List reactions retrieve successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Reaction"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/users/{user_id}/posts/{post_id}/reactions/{emoji_name}":
+    delete:
+      tags:
+        - reactions
+      summary: Remove a reaction from a post
+      description: |
+        Deletes a reaction made by a user from the given post.
+        ##### Permissions
+        Must be user or have `manage_system` permission.
+      operationId: DeleteReaction
+      parameters:
+        - name: user_id
+          in: path
+          description: ID of the user
+          required: true
+          schema:
+            type: string
+        - name: post_id
+          in: path
+          description: ID of the post
+          required: true
+          schema:
+            type: string
+        - name: emoji_name
+          in: path
+          description: emoji name
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Reaction 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"
+  /api/v4/posts/ids/reactions:
+    post:
+      tags:
+        - reactions
+      summary: Bulk get the reaction for posts
+      description: |
+        Get a list of reactions made by all users to a given post.
+        ##### Permissions
+        Must have `read_channel` permission for the channel the post is in.
+
+        __Minimum server version__: 5.8
+      operationId: GetBulkReactions
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+        description: Array of post IDs
+        required: true
+      responses:
+        "200":
+          description: Reactions retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostIdToReactionsMap"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"

api/v4/source/roles.yaml

@@ -0,0 +1,214 @@
+  "/api/v4/roles":
+    get:
+      tags:
+        - roles
+      summary: Get a list of all the roles
+      description: |
+        ##### Permissions
+
+        `manage_system` permission is required.
+
+        __Minimum server version__: 5.33
+      operationId: GetAllRoles
+      responses:
+        "200":
+          description: Roles retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Role"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            roles, resp := Client.GetAllRoles()
+
+  "/api/v4/roles/{role_id}":
+    get:
+      tags:
+        - roles
+      summary: Get a role
+      description: |
+        Get a role from the provided role id.
+
+        ##### Permissions
+        Requires an active session but no other permissions.
+
+        __Minimum server version__: 4.9
+      operationId: GetRole
+      parameters:
+        - name: role_id
+          in: path
+          description: Role GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Role retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Role"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            role, resp := Client.GetRole(<ROLEID>, "")
+  "/api/v4/roles/name/{role_name}":
+    get:
+      tags:
+        - roles
+      summary: Get a role
+      description: |
+        Get a role from the provided role name.
+
+        ##### Permissions
+        Requires an active session but no other permissions.
+
+        __Minimum server version__: 4.9
+      operationId: GetRoleByName
+      parameters:
+        - name: role_name
+          in: path
+          description: Role Name
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Role retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Role"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            role, resp := Client.GetRoleByName(<ROLENAME>, "")
+  "/api/v4/roles/{role_id}/patch":
+    put:
+      tags:
+        - roles
+      summary: Patch a role
+      description: >
+        Partially update a role 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
+
+        `manage_system` permission is required.
+
+
+        __Minimum server version__: 4.9
+      operationId: PatchRole
+      parameters:
+        - name: role_id
+          in: path
+          description: Role GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                permissions:
+                  type: array
+                  items:
+                    type: string
+                  description: The permissions the role should grant.
+        description: Role object to be updated
+        required: true
+      responses:
+        "200":
+          description: Role patch successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Role"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v4/roles/names:
+    post:
+      tags:
+        - roles
+      summary: Get a list of roles by name
+      description: |
+        Get a list of roles from their names.
+
+        ##### Permissions
+        Requires an active session but no other permissions.
+
+        __Minimum server version__: 4.9
+      operationId: GetRolesByNames
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+        description: List of role names
+        required: true
+      responses:
+        "200":
+          description: Role list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Role"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            roleNames := []string{<NAME OF ROLE1>, <NAME OF ROLE2>, ...}
+
+            roles, resp := Client.GetRolesByNames(roleNames)

api/v4/source/saml.yaml

@@ -0,0 +1,323 @@
+  /api/v4/saml/metadata:
+    get:
+      tags:
+        - SAML
+      summary: Get metadata
+      description: |
+        Get SAML metadata from the server. SAML must be configured properly.
+        ##### Permissions
+        No permission required.
+      operationId: GetSamlMetadata
+      responses:
+        "200":
+          description: SAML metadata retrieval successful
+          content:
+            application/json:
+              schema:
+                type: string
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/saml/metadatafromidp:
+    post:
+      tags:
+        - SAML
+      summary: Get metadata from Identity Provider
+      description: |
+        Get SAML metadata from the Identity Provider. SAML must be configured properly.
+        ##### Permissions
+        No permission required.
+      operationId: GetSamlMetadataFromIdp
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                saml_metadata_url:
+                  type: string
+                  description: The URL from which to retrieve the SAML IDP data.
+      responses:
+        "200":
+          description: SAML metadata retrieval successful
+          content:
+            application/json:
+              schema:
+                type: string
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/saml/certificate/idp:
+    post:
+      tags:
+        - SAML
+      summary: Upload IDP certificate
+      description: >
+        Upload the IDP certificate to be used with your SAML configuration. The
+        server will pick a hard-coded filename for the IdpCertificateFile
+        setting in your `config.json`.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: UploadSamlIdpCertificate
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                certificate:
+                  description: The IDP certificate file
+                  type: string
+                  format: binary
+              required:
+                - certificate
+      responses:
+        "200":
+          description: SAML certificate upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - SAML
+      summary: Remove IDP certificate
+      description: >
+        Delete the current IDP certificate being used with your SAML
+        configuration. This will also disable SAML on your system as this
+        certificate is required for SAML.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: DeleteSamlIdpCertificate
+      responses:
+        "200":
+          description: SAML certificate delete 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/saml/certificate/public:
+    post:
+      tags:
+        - SAML
+      summary: Upload public certificate
+      description: >
+        Upload the public certificate to be used for encryption with your SAML
+        configuration. The server will pick a hard-coded filename for the
+        PublicCertificateFile setting in your `config.json`.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: UploadSamlPublicCertificate
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                certificate:
+                  description: The public certificate file
+                  type: string
+                  format: binary
+              required:
+                - certificate
+      responses:
+        "200":
+          description: SAML certificate upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - SAML
+      summary: Remove public certificate
+      description: >
+        Delete the current public certificate being used with your SAML
+        configuration. This will also disable encryption for SAML on your system
+        as this certificate is required for that.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: DeleteSamlPublicCertificate
+      responses:
+        "200":
+          description: SAML certificate delete 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/saml/certificate/private:
+    post:
+      tags:
+        - SAML
+      summary: Upload private key
+      description: >
+        Upload the private key to be used for encryption with your SAML
+        configuration. The server will pick a hard-coded filename for the
+        PrivateKeyFile setting in your `config.json`.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: UploadSamlPrivateCertificate
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                certificate:
+                  description: The private key file
+                  type: string
+                  format: binary
+              required:
+                - certificate
+      responses:
+        "200":
+          description: SAML certificate upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - SAML
+      summary: Remove private key
+      description: >
+        Delete the current private key being used with your SAML configuration.
+        This will also disable encryption for SAML on your system as this key is
+        required for that.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: DeleteSamlPrivateCertificate
+      responses:
+        "200":
+          description: SAML certificate delete 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/saml/certificate/status:
+    get:
+      tags:
+        - SAML
+      summary: Get certificate status
+      description: >
+        Get the status of the uploaded certificates and keys in use by your SAML
+        configuration.
+
+        ##### Permissions
+
+        Must have `sysconsole_write_authentication` permission.
+      operationId: GetSamlCertificateStatus
+      responses:
+        "200":
+          description: SAML certificate status retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SamlCertificateStatus"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/saml/reset_auth_data:
+    post:
+      tags:
+        - SAML
+      summary: Reset AuthData to Email
+      description: >
+        Reset the AuthData field of SAML users to their email. This is meant to be
+        used when the "id" attribute is set to an empty value ("") from a previously
+        non-empty value.
+
+        __Minimum server version__: 5.35
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+      operationId: ResetSamlAuthDataToEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                include_deleted:
+                  type: boolean
+                  default: false
+                  description: Whether to include deleted users.
+                dry_run:
+                  type: boolean
+                  default: false
+                  description: If set to true, the number of users who would be affected is returned.
+                user_ids:
+                  type: array
+                  items:
+                    type: string
+                  default: []
+                  description: If set to a non-empty array, then users whose IDs are not in the array will be excluded.
+      responses:
+        "200":
+          description: AuthData successfully reset
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  num_affected:
+                    type: integer
+                    description: The number of users whose AuthData field was reset.
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"

api/v4/source/schemes.yaml

@@ -0,0 +1,341 @@
+  /api/v4/schemes:
+    get:
+      tags:
+        - schemes
+      summary: Get the schemes.
+      description: >
+        Get a page of schemes. Use the query parameters to modify the behaviour
+        of this endpoint.
+
+
+        ##### Permissions
+
+        Must have `manage_system` permission.
+
+
+        __Minimum server version__: 5.0
+      operationId: GetSchemes
+      parameters:
+        - name: scope
+          in: query
+          description: Limit the results returned to the provided scope, either `team` or
+            `channel`.
+          schema:
+            type: string
+            default: ""
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of schemes per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Scheme list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Scheme"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    post:
+      tags:
+        - schemes
+      summary: Create a scheme
+      description: |
+        Create a new scheme.
+
+        ##### Permissions
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.0
+      operationId: CreateScheme
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - scope
+              properties:
+                name:
+                  type: string
+                  description: The name of the scheme
+                description:
+                  type: string
+                  description: The description of the scheme
+                scope:
+                  type: string
+                  description: The scope of the scheme ("team" or "channel")
+        description: Scheme object to create
+        required: true
+      responses:
+        "201":
+          description: Scheme creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Scheme"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/schemes/{scheme_id}":
+    get:
+      tags:
+        - schemes
+      summary: Get a scheme
+      description: |
+        Get a scheme from the provided scheme id.
+
+        ##### Permissions
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.0
+      operationId: GetScheme
+      parameters:
+        - name: scheme_id
+          in: path
+          description: Scheme GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Scheme retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Scheme"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            scheme, resp := Client.GetScheme(<SCHEMEID>, "")
+    delete:
+      tags:
+        - schemes
+      summary: Delete a scheme
+      description: |
+        Soft deletes a scheme, by marking the scheme as deleted in the database.
+
+        ##### Permissions
+        Must have `manage_system` permission.
+
+        __Minimum server version__: 5.0
+      operationId: DeleteScheme
+      parameters:
+        - name: scheme_id
+          in: path
+          description: ID of the scheme to delete
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Scheme 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"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  "/api/v4/schemes/{scheme_id}/patch":
+    put:
+      tags:
+        - schemes
+      summary: Patch a scheme
+      description: >
+        Partially update a scheme 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
+
+        `manage_system` permission is required.
+
+
+        __Minimum server version__: 5.0
+      operationId: PatchScheme
+      parameters:
+        - name: scheme_id
+          in: path
+          description: Scheme GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: The human readable name of the scheme
+                description:
+                  type: string
+                  description: The description of the scheme
+        description: Scheme object to be updated
+        required: true
+      responses:
+        "200":
+          description: Scheme patch successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Scheme"
+        "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/schemes/{scheme_id}/teams":
+    get:
+      tags:
+        - schemes
+      summary: Get a page of teams which use this scheme.
+      description: >
+        Get a page of teams which use this scheme. The provided Scheme ID should
+        be for a Team-scoped Scheme.
+
+        Use the query parameters to modify the behaviour of this endpoint.
+
+
+        ##### Permissions
+
+        `manage_system` permission is required.
+
+
+        __Minimum server version__: 5.0
+      operationId: GetTeamsForScheme
+      parameters:
+        - name: scheme_id
+          in: path
+          description: Scheme 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 teams per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Team list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Team"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/schemes/{scheme_id}/channels":
+    get:
+      tags:
+        - schemes
+      summary: Get a page of channels which use this scheme.
+      description: >
+        Get a page of channels which use this scheme. The provided Scheme ID
+        should be for a Channel-scoped Scheme.
+
+        Use the query parameters to modify the behaviour of this endpoint.
+
+
+        ##### Permissions
+
+        `manage_system` permission is required.
+
+
+        __Minimum server version__: 5.0
+      operationId: GetChannelsForScheme
+      parameters:
+        - name: scheme_id
+          in: path
+          description: Scheme 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 channels per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Channel list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Channel"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"

api/v4/source/service_terms.yaml

@@ -0,0 +1,45 @@
+  /api/v4/terms_of_service:
+    get:
+      tags:
+        - terms of service
+      summary: Get latest terms of service
+      description: |
+        Get latest terms of service from the server
+
+        __Minimum server version__: 5.4
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetTermsOfService
+      responses:
+        "200":
+          description: Terms of service fetched successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TermsOfService"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags:
+        - terms of service
+      summary: Creates a new terms of service
+      description: |
+        Creates new terms of service
+
+        __Minimum server version__: 5.4
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: CreateTermsOfService
+      responses:
+        "200":
+          description: terms of service fetched successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TermsOfService"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"

api/v4/source/sharedchannels.yaml

@@ -0,0 +1,116 @@
+  "/api/v4/sharedchannels/{team_id}":
+    get:
+      tags:
+        - shared channels
+      summary: Get all shared channels for team.
+      description: |
+        Get all shared channels for a team.
+
+        __Minimum server version__: 5.50
+
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetAllSharedChannels
+      parameters:
+        - name: team_id
+          in: path
+          description: Team Id
+          required: true
+          schema:
+            type: string
+        - name: page
+          description: The page to select.
+          in: query
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          description: The number of sharedchannels per page.
+          in: query
+          schema:
+            type: integer
+            default: 0
+      responses:
+        "200":
+          description: Shared channels fetch successful. Result may be empty.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SharedChannel"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            teamID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            shared_channels, err := Client.GetAllSharedChannels(teamID, 0, 100)
+        - lang: curl
+          source: |
+            curl -X POST \
+              'http://your-mattermost-url.com/api/v4/sharedchannels/4xp9fdt77pncbef59f4k1qe83o' \
+              -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'
+
+  "/api/v4/sharedchannels/remote_info/{remote_id}":
+    get:
+      tags:
+        - shared channels
+      summary: Get remote cluster info by ID for user.
+      description: |
+        Get remote cluster info based on remoteId.
+
+        __Minimum server version__: 5.50
+
+        ##### Permissions
+        Must be authenticated and user must belong to at least one channel shared with the remote cluster.
+      operationId: GetRemoteClusterInfo
+      parameters:
+        - name: remote_id
+          in: path
+          description: Remote Cluster GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Remote cluster info retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteClusterInfo"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-code-samples:
+        - lang: Go
+          source: |
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            remoteID := "4xp9fdt77pncbef59f4k1qe83o"
+
+            info, err := Client.GetRemoteClusterInfo(remoteID)
+        - lang: curl
+          source: |
+            curl -X POST \
+              'http://your-mattermost-url.com/api/v4/sharedchannels/getremote/4xp9fdt77pncbef59f4k1qe83o' \
+              -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'
+

api/v4/source/status.yaml

@@ -0,0 +1,280 @@
+  "/api/v4/users/{user_id}/status":
+    get:
+      tags:
+        - status
+      summary: Get user status
+      description: |
+        Get user status by id from the server.
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetUserStatus
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: User status retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Status"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags:
+        - status
+      summary: Update user status
+      description: >
+        Manually set a user's status. When setting a user's status, the status
+        will remain that value until set "online" again, which will return the
+        status to being automatically updated based on user activity.
+
+        ##### Permissions
+
+        Must have `edit_other_users` permission for the team.
+      operationId: UpdateUserStatus
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - status
+                - user_id
+              properties:
+                user_id:
+                  type: string
+                  description: User ID
+                status:
+                  type: string
+                  description: User status, can be `online`, `away`, `offline` and `dnd`
+                dnd_end_time:
+                  type: integer
+                  description: Time in epoch seconds at which a dnd status would be unset.
+        description: Status object that is to be updated
+        required: true
+      responses:
+        "200":
+          description: User status update successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Status"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v4/users/status/ids:
+    post:
+      tags:
+        - status
+      summary: Get user statuses by id
+      description: |
+        Get a list of user statuses by id from the server.
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetUsersStatusesByIds
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
+        description: List of user ids to fetch
+        required: true
+      responses:
+        "200":
+          description: User statuses retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Status"
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  "/api/v4/users/{user_id}/status/custom":
+    put:
+      tags:
+        - status
+      summary: Update user custom status
+      description: |
+        Updates a user's custom status by setting the value in the user's props and updates the user. Also save the given custom status to the recent custom statuses in the user's props
+        ##### Permissions
+        Must be logged in as the user whose custom status is being updated.
+      operationId: UpdateUserCustomStatus
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - emoji
+                - text
+              properties:
+                emoji:
+                  type: string
+                  description: Any emoji
+                text:
+                  type: string
+                  description: Any custom status text
+                duration:
+                  type: string
+                  description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time`
+                expires_at:
+                  type: string
+                  description: The time at which custom status should be expired. It should be in ISO format.
+        description: Custom status object that is to be updated
+        required: true
+      responses:
+        "200":
+          description: User custom status update successful
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+    delete:
+      tags:
+        - status
+      summary: Unsets user custom status
+      description: |
+        Unsets a user's custom status by updating the user's props and updates the user
+        ##### Permissions
+        Must be logged in as the user whose custom status is being removed.
+      operationId: UnsetUserCustomStatus
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: User custom status delete successful
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  "/api/v4/users/{user_id}/status/custom/recent":
+    delete:
+      tags:
+        - status
+      summary: Delete user's recent custom status
+      description: |
+        Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user.
+        ##### Permissions
+        Must be logged in as the user whose recent custom status is being deleted.
+      operationId: RemoveRecentCustomStatus
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - emoji
+                - text
+                - duration
+                - expires_at
+              properties:
+                emoji:
+                  type: string
+                  description: Any emoji
+                text:
+                  type: string
+                  description: Any custom status text
+                duration:
+                  type: string
+                  description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time`
+                expires_at:
+                  type: string
+                  description: The time at which custom status should be expired. It should be in ISO format.
+        description: Custom Status object that is to be removed from the recent custom statuses.
+        required: true
+      responses:
+        "200":
+          description: User recent custom status delete successful
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  "/api/v4/users/{user_id}/status/custom/recent/delete":
+    post:
+      tags:
+        - status
+      summary: Delete user's recent custom status
+      description: |
+        Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user.
+        ##### Permissions
+        Must be logged in as the user whose recent custom status is being deleted.
+      operationId: PostUserRecentCustomStatusDelete
+      parameters:
+        - name: user_id
+          in: path
+          description: User ID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - emoji
+                - text
+                - duration
+                - expires_at
+              properties:
+                emoji:
+                  type: string
+                  description: Any emoji
+                text:
+                  type: string
+                  description: Any custom status text
+                duration:
+                  type: string
+                  description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time`
+                expires_at:
+                  type: string
+                  description: The time at which custom status should be expired. It should be in ISO format.
+        description: Custom Status object that is to be removed from the recent custom statuses.
+        required: true
+      responses:
+        "200":
+          description: User recent custom status delete successful
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"

api/v4/source/uploads.yaml

@@ -0,0 +1,195 @@
+  "/api/v4/uploads":
+    post:
+      tags:
+        - uploads
+      summary: Create an upload
+      description: >
+        Creates a new upload session.
+
+
+        __Minimum server version__: 5.28
+
+        ##### Permissions
+
+        Must have `upload_file` permission.
+
+      operationId: CreateUpload
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - channel_id
+                - filename
+                - file_size
+              properties:
+                channel_id:
+                  description: The ID of the channel to upload to.
+                  type: string
+                filename:
+                  description: The name of the file to upload.
+                  type: string
+                file_size:
+                  description: The size of the file to upload in bytes.
+                  type: integer
+                  format: int64
+        required: true
+      responses:
+        "201":
+          description: Upload creation successful.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UploadSession"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "413":
+          $ref: "#/components/responses/TooLarge"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+            us := &model.UploadSession{
+              ChannelId: "4i6jn8r483nnuqnibnmgz8jo4o",
+              Filename: "file.png",
+              FileSize: 512000,
+            }
+
+            us, response := Client.CreateUpload(us)
+        - lang: Curl
+          source: |
+            curl 'http://localhost:8065/api/v4/uploads' \                                                                                                          
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \
+            -H 'Content-Type: application/json' \
+            --data-binary '{"channel_id": "4i6jn8r483nnuqnibnmgz8jo4o", "filename": "test.png", "file_size": 512000}'
+  "/api/v4/uploads/{upload_id}":
+    get:
+      tags:
+        - uploads
+      summary: Get an upload session
+      description: |
+        Gets an upload session that has been previously created.
+
+        ##### Permissions
+        Must be logged in as the user who created the upload session.
+      operationId: GetUpload
+      parameters:
+        - name: upload_id
+          in: path
+          description: The ID of the upload session 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"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import "github.com/mattermost/mattermost-server/v5/model"
+
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+
+            Client.Login("email@domain.com", "Password1")
+
+            us, response := Client.GetUpload("nuyrh9ymridqmenof7exe3a6aw")
+        - lang: Curl
+          source: |
+            curl 'http://localhost:8065/api/v4/uploads/nuyrh9ymridqmenof7exe3a6aw' \                                                                                            
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'
+    post:
+      tags:
+        - uploads
+      summary: Perform a file upload
+      description: |
+        Starts or resumes a file upload.  
+        To resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object.
+
+        The request body can be in one of two formats:
+        - Binary file content streamed in request's body
+        - multipart/form-data
+
+        ##### Permissions
+        Must be logged in as the user who created the upload session.
+      operationId: UploadData
+      parameters:
+        - name: upload_id
+          in: path
+          description: The ID of the upload session the data belongs to.
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+      responses:
+        "201":
+          description: Upload successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FileInfo"
+        "204":
+          description: Upload incomplete
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "413":
+          $ref: "#/components/responses/TooLarge"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+      x-code-samples:
+        - lang: Go
+          source: >
+            import (
+              "os"
+
+              "github.com/mattermost/mattermost-server/v5/model"
+            )
+
+            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
+            Client.Login("email@domain.com", "Password1")
+
+            file, err := os.Open("file.png")
+            if err != nil {
+              fmt.Fprintf(os.Stderr, "%v\n", err)
+              return
+            }
+
+            info, err := Client.UploadData(us, file)
+        - lang: Curl
+          source: |
+            # Binary file content in request's body
+            curl -X POST 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' --data-binary @file.png
+
+            # multipart/form-data upload
+            curl 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \
+            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' -F data=@file.png

api/v4/source/usage.yaml

@@ -0,0 +1,52 @@
+  /api/v4/usage/posts:
+    get:
+      tags:
+        - usage
+      summary: Get current usage of posts
+      description: >
+        Retrieve rounded off total no. of posts for this instance.
+        Example: returns 4000 instead of 4321
+
+        ##### Permissions
+
+        Must be authenticated.
+
+        __Minimum server version__: 7.0
+      operationId: GetPostsUsage
+      responses:
+        "200":
+          description: Total no. of posts returned successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostsUsage"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/usage/storage:
+    get:
+      tags:
+        - usage
+      summary: Get the total file storage usage for the instance in bytes.
+      description: >
+        Get the total file storage usage for the instance in bytes rounded down to the most significant digit.
+        Example: returns 4000 instead of 4321
+
+        ##### Permissions
+
+        Must be authenticated.
+
+        __Minimum server version__: 7.1
+      operationId: GetStorageUsage
+      responses:
+        "200":
+          description: The total file storage usage for the instance in bytes rounded down to the most significant digit.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StorageUsage"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"

api/v4/source/webhooks.yaml

@@ -0,0 +1,521 @@
+  /api/v4/hooks/incoming:
+    post:
+      tags:
+        - webhooks
+      summary: Create an incoming webhook
+      description: |
+        Create an incoming webhook for a channel.
+        ##### Permissions
+        `manage_webhooks` for the team the webhook is in.
+
+        `manage_others_incoming_webhooks` for the team the webhook is in if the user is different than the requester.
+      operationId: CreateIncomingWebhook
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - channel_id
+              properties:
+                channel_id:
+                  type: string
+                  description: The ID of a public channel or private group that receives
+                    the webhook payloads.
+                user_id:
+                  type: string
+                  description: The ID of the owner of the webhook if different than the requester. Required for [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).
+                display_name:
+                  type: string
+                  description: The display name for this incoming webhook
+                description:
+                  type: string
+                  description: The description for this incoming webhook
+                username:
+                  type: string
+                  description: The username this incoming webhook will post as.
+                icon_url:
+                  type: string
+                  description: The profile picture this incoming webhook will use when
+                    posting.
+        description: Incoming webhook to be created
+        required: true
+      responses:
+        "201":
+          description: Incoming webhook creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IncomingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    get:
+      tags:
+        - webhooks
+      summary: List incoming webhooks
+      description: >
+        Get a page of a list of incoming webhooks. Optionally filter for a
+        specific team using query parameters.
+
+        ##### Permissions
+
+        `manage_webhooks` for the system or `manage_webhooks` for the specific team.
+      operationId: GetIncomingWebhooks
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of hooks per page.
+          schema:
+            type: integer
+            default: 60
+        - name: team_id
+          in: query
+          description: The ID of the team to get hooks for.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Incoming webhooks retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/IncomingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/hooks/incoming/{hook_id}":
+    get:
+      tags:
+        - webhooks
+      summary: Get an incoming webhook
+      description: >
+        Get an incoming webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: GetIncomingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: Incoming Webhook GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Webhook retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IncomingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - webhooks
+      summary: Delete an incoming webhook
+      description: >
+        Delete an incoming webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: DeleteIncomingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: Incoming webhook GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Webhook 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"
+    put:
+      tags:
+        - webhooks
+      summary: Update an incoming webhook
+      description: >
+        Update an incoming webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: UpdateIncomingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: Incoming Webhook GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+                - channel_id
+                - display_name
+                - description
+              properties:
+                id:
+                  type: string
+                  description: Incoming webhook GUID
+                channel_id:
+                  type: string
+                  description: The ID of a public channel or private group that receives
+                    the webhook payloads.
+                display_name:
+                  type: string
+                  description: The display name for this incoming webhook
+                description:
+                  type: string
+                  description: The description for this incoming webhook
+                username:
+                  type: string
+                  description: The username this incoming webhook will post as.
+                icon_url:
+                  type: string
+                  description: The profile picture this incoming webhook will use when
+                    posting.
+        description: Incoming webhook to be updated
+        required: true
+      responses:
+        "200":
+          description: Webhook update successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IncomingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v4/hooks/outgoing:
+    post:
+      tags:
+        - webhooks
+      summary: Create an outgoing webhook
+      description: |
+        Create an outgoing webhook for a team.
+        ##### Permissions
+        `manage_webhooks` for the team the webhook is in.
+
+        `manage_others_outgoing_webhooks` for the team the webhook is in if the user is different than the requester.
+      operationId: CreateOutgoingWebhook
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - team_id
+                - display_name
+                - trigger_words
+                - callback_urls
+              properties:
+                team_id:
+                  description: The ID of the team that the webhook watchs
+                  type: string
+                channel_id:
+                  description: The ID of a public channel that the webhook watchs
+                  type: string
+                creator_id:
+                  description: The ID of the owner of the webhook if different than the requester. Required in [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).
+                  type: string
+                description:
+                  description: The description for this outgoing webhook
+                  type: string
+                display_name:
+                  description: The display name for this outgoing webhook
+                  type: string
+                trigger_words:
+                  description: List of words for the webhook to trigger on
+                  type: array
+                  items:
+                    type: string
+                trigger_when:
+                  description: When to trigger the webhook, `0` when a trigger word is
+                    present at all and `1` if the message starts with a trigger
+                    word
+                  type: integer
+                callback_urls:
+                  description: The URLs to POST the payloads to when the webhook is
+                    triggered
+                  type: array
+                  items:
+                    type: string
+                content_type:
+                  description: The format to POST the data in, either `application/json` or
+                    `application/x-www-form-urlencoded`
+                  default: application/x-www-form-urlencoded
+                  type: string
+        description: Outgoing webhook to be created
+        required: true
+      responses:
+        "201":
+          description: Outgoing webhook creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OutgoingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    get:
+      tags:
+        - webhooks
+      summary: List outgoing webhooks
+      description: >
+        Get a page of a list of outgoing webhooks. Optionally filter for a
+        specific team or channel using query parameters.
+
+        ##### Permissions
+
+        `manage_webhooks` for the system or `manage_webhooks` for the specific team/channel.
+      operationId: GetOutgoingWebhooks
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of hooks per page.
+          schema:
+            type: integer
+            default: 60
+        - name: team_id
+          in: query
+          description: The ID of the team to get hooks for.
+          schema:
+            type: string
+        - name: channel_id
+          in: query
+          description: The ID of the channel to get hooks for.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Outgoing webhooks retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/OutgoingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/hooks/outgoing/{hook_id}":
+    get:
+      tags:
+        - webhooks
+      summary: Get an outgoing webhook
+      description: >
+        Get an outgoing webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: GetOutgoingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: Outgoing webhook GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Outgoing webhook retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OutgoingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - webhooks
+      summary: Delete an outgoing webhook
+      description: >
+        Delete an outgoing webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: DeleteOutgoingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: Outgoing webhook GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Webhook 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"
+    put:
+      tags:
+        - webhooks
+      summary: Update an outgoing webhook
+      description: >
+        Update an outgoing webhook given the hook id.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: UpdateOutgoingWebhook
+      parameters:
+        - name: hook_id
+          in: path
+          description: outgoing Webhook GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+                - channel_id
+                - display_name
+                - description
+              properties:
+                id:
+                  type: string
+                  description: Outgoing webhook GUID
+                channel_id:
+                  type: string
+                  description: The ID of a public channel or private group that receives
+                    the webhook payloads.
+                display_name:
+                  type: string
+                  description: The display name for this incoming webhook
+                description:
+                  type: string
+                  description: The description for this incoming webhook
+        description: Outgoing webhook to be updated
+        required: true
+      responses:
+        "200":
+          description: Webhook update successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OutgoingWebhook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/hooks/outgoing/{hook_id}/regen_token":
+    post:
+      tags:
+        - webhooks
+      summary: Regenerate the token for the outgoing webhook.
+      description: >
+        Regenerate the token for the outgoing webhook.
+
+        ##### Permissions
+
+        `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
+      operationId: RegenOutgoingHookToken
+      parameters:
+        - name: hook_id
+          in: path
+          description: Outgoing webhook GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Webhook token regenerate 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"