mirror of
https://github.com/mattermost/mattermost.git
synced 2026-05-23 18:55:27 -04:00
55496c07c1
* Update API docs * Coderabbit comments * Address feedback * Address feedback * Coderabbit feedback
1644 lines
49 KiB
YAML
1644 lines
49 KiB
YAML
/api/v4/system/timezones:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Retrieve a list of supported timezones
|
|
description: >
|
|
__Minimum server version__: 3.10
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: GetSupportedTimezone
|
|
responses:
|
|
"200":
|
|
description: List of timezones retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/system/ping:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Check system health
|
|
description: >
|
|
Check if the server is up and healthy based on the configuration setting
|
|
`GoRoutineHealthThreshold`. If `GoRoutineHealthThreshold` and the number
|
|
of goroutines on the server exceeds that threshold the server is
|
|
considered unhealthy. If `GoRoutineHealthThreshold` is not set or the
|
|
number of goroutines is below the threshold the server is considered
|
|
healthy.
|
|
|
|
__Minimum server version__: 3.10
|
|
|
|
If a "device_id" is passed in the query, it will test the Push Notification
|
|
Proxy in order to discover whether the device is able to receive notifications.
|
|
The response will have a "CanReceiveNotifications" property with one of the
|
|
following values:
|
|
- true: It can receive notifications
|
|
- false: It cannot receive notifications
|
|
- unknown: There has been an unknown error, and it is not certain whether it can
|
|
receive notifications.
|
|
|
|
__Minimum server version__: 6.5
|
|
|
|
If "use_rest_semantics" is set to true in the query, the endpoint will not return
|
|
an error status code in the header if the request is somehow completed successfully.
|
|
|
|
__Minimum server version__: 9.6
|
|
|
|
##### Permissions
|
|
|
|
None. Authentication is not required for this endpoint.
|
|
|
|
##### Response Details
|
|
|
|
The response varies based on query parameters and authentication:
|
|
|
|
- **Basic response** (no parameters): Returns basic server information including
|
|
`status`, mobile app versions, and active search backend.
|
|
|
|
- **Enhanced response** (`get_server_status=true`): Additionally returns
|
|
`database_status` and `filestore_status` to verify backend connectivity.
|
|
Authentication is not required.
|
|
|
|
- **Admin response** (`get_server_status=true` with `manage_system` permission):
|
|
Additionally returns `root_status` indicating whether the server is running as root.
|
|
Requires authentication with `manage_system` permission.
|
|
operationId: GetPing
|
|
parameters:
|
|
- name: get_server_status
|
|
in: query
|
|
description: >
|
|
Check the status of the database and file storage as well.
|
|
When true, adds `database_status` and `filestore_status` to the response.
|
|
If authenticated with `manage_system` permission, also adds `root_status`.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
- name: device_id
|
|
in: query
|
|
description: Check whether this device id can receive push notifications
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: use_rest_semantics
|
|
in: query
|
|
description: Returns 200 status code even if the server status is unhealthy.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
description: Status of the system
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SystemStatusResponse"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/websocket:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Open a WebSocket connection
|
|
description: |
|
|
Upgrades the HTTP connection to a WebSocket connection used for real-time events and websocket actions.
|
|
|
|
##### Permissions
|
|
No permission required to connect. Authentication can be performed via standard API auth (cookie/header)
|
|
or by sending an `authentication_challenge` action after connecting.
|
|
operationId: ConnectWebSocket
|
|
security: []
|
|
parameters:
|
|
- name: connection_id
|
|
in: query
|
|
description: Existing connection identifier for reconnect flows.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: sequence_number
|
|
in: query
|
|
description: Last received sequence number for reconnect flows.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: posted_ack
|
|
in: query
|
|
description: Whether post acknowledgement events are enabled for this connection.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
- name: disconnect_err_code
|
|
in: query
|
|
description: Optional close code used by clients to indicate disconnect reason.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"101":
|
|
description: Switching Protocols
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
|
|
/manualtest:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Run manual testing helpers
|
|
description: |
|
|
Invokes manual test helpers used by developers and automated manual test scenarios.
|
|
This endpoint is only registered when `ServiceSettings.EnableTesting` is enabled.
|
|
|
|
##### Permissions
|
|
|
|
None. Authentication is not required; this route uses the same handler stack as other unauthenticated API handlers (`APIHandler`).
|
|
|
|
__Security note:__ Only enable `EnableTesting` on non-production, developer-oriented deployments.
|
|
operationId: ManualTest
|
|
security: []
|
|
parameters:
|
|
- name: test
|
|
in: query
|
|
description: Name of the manual test to run.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: uid
|
|
in: query
|
|
description: Optional unique value used to randomize generated resources.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: username
|
|
in: query
|
|
description: Optional username used for helper account creation.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: teamname
|
|
in: query
|
|
description: Optional team display name used for helper team creation.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"307":
|
|
description: Manual test setup completed and redirected to the default channel.
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
"/api/v4/system/notices/{team_id}":
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get notices for logged in user in specified team
|
|
description: >
|
|
Will return appropriate product notices for current user in the team specified by team_id parameter.
|
|
|
|
__Minimum server version__: 5.26
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: GetNotices
|
|
parameters:
|
|
- name: clientVersion
|
|
in: query
|
|
description: Version of the client (desktop/mobile/web) that issues the request
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: locale
|
|
in: query
|
|
description: Client locale
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: client
|
|
in: query
|
|
description: Client type (web/mobile-ios/mobile-android/desktop)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: team_id
|
|
in: path
|
|
description: ID of the team
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: List notices retrieve successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Notice"
|
|
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/system/notices/view:
|
|
put:
|
|
tags:
|
|
- system
|
|
summary: Update notices as 'viewed'
|
|
description: >
|
|
Will mark the specified notices as 'viewed' by the logged in user.
|
|
|
|
__Minimum server version__: 5.26
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: MarkNoticesViewed
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of notice IDs
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Update successfull
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/system/onboarding/complete:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get first admin onboarding completion status
|
|
description: >
|
|
Get whether first admin onboarding is complete.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: GetOnboardingComplete
|
|
responses:
|
|
"200":
|
|
description: Onboarding completion state retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/System"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Complete first admin onboarding
|
|
description: >
|
|
Mark first admin onboarding as complete and optionally trigger plugin installation.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: CompleteOnboarding
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
organization:
|
|
type: string
|
|
description: Organization name for self-hosted onboarding.
|
|
install_plugins:
|
|
type: array
|
|
description: Marketplace plugin IDs to install as part of onboarding.
|
|
items:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Onboarding completion successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/system/e2e/ai_bridge:
|
|
put:
|
|
tags:
|
|
- system
|
|
summary: Configure AI bridge E2E test helper
|
|
description: >
|
|
Configure the in-memory AI bridge test helper used by end-to-end tests to
|
|
mock agent availability, agent/service listings, queued completion
|
|
responses, and test-only AI feature flag overrides.
|
|
|
|
This endpoint is only available when `EnableTesting` is enabled. `EnableTesting`
|
|
is intended only for isolated non-production environments and must never be
|
|
enabled in production.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: SetAIBridgeTestHelper
|
|
requestBody:
|
|
description: AI bridge E2E helper configuration
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AIBridgeTestHelperConfig"
|
|
responses:
|
|
"200":
|
|
description: AI bridge test helper configured successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AIBridgeTestHelperState"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get AI bridge E2E test helper state
|
|
description: >
|
|
Retrieve the current in-memory AI bridge test helper state used for end-to-end tests.
|
|
|
|
This endpoint is only available when `EnableTesting` is enabled. `EnableTesting`
|
|
is intended only for isolated non-production environments and must never be
|
|
enabled in production.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetAIBridgeTestHelper
|
|
responses:
|
|
"200":
|
|
description: AI bridge test helper state retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AIBridgeTestHelperState"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
delete:
|
|
tags:
|
|
- system
|
|
summary: Reset AI bridge E2E test helper
|
|
description: >
|
|
Reset the in-memory AI bridge test helper state used for end-to-end tests.
|
|
|
|
This endpoint is only available when `EnableTesting` is enabled. `EnableTesting`
|
|
is intended only for isolated non-production environments and must never be
|
|
enabled in production.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: DeleteAIBridgeTestHelper
|
|
responses:
|
|
"200":
|
|
description: AI bridge test helper was reset successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
/api/v4/database/recycle:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Recycle database connections
|
|
description: >
|
|
Recycle database connections by closing and reconnecting all connections
|
|
to master and read replica databases.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: DatabaseRecycle
|
|
responses:
|
|
"200":
|
|
description: Database recycle successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/email/test:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Send a test email
|
|
description: >
|
|
Send a test email to make sure you have your email settings configured
|
|
correctly. 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.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: TestEmail
|
|
requestBody:
|
|
description: Mattermost configuration
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
responses:
|
|
"200":
|
|
description: Email successful sent
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/notifications/test:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Send a test notification
|
|
description: >
|
|
Send a test notification to make sure you have your notification settings
|
|
configured correctly.
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: TestNotification
|
|
responses:
|
|
"200":
|
|
description: Notification successfully sent
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/site_url/test:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Checks the validity of a Site URL
|
|
description: >
|
|
Sends a Ping request to the mattermost server using the specified Site
|
|
URL.
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
|
|
|
|
__Minimum server version__: 5.16
|
|
operationId: TestSiteURL
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- site_url
|
|
properties:
|
|
site_url:
|
|
type: string
|
|
description: The Site URL to test
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Site URL is valid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/file/s3_test:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Test AWS S3 connection
|
|
description: >
|
|
Send a test to validate if can connect to AWS S3. 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.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 4.8
|
|
operationId: TestS3Connection
|
|
requestBody:
|
|
description: Mattermost configuration
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
responses:
|
|
"200":
|
|
description: S3 Test successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/config:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get configuration
|
|
description: |
|
|
Retrieve the current server configuration
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: GetConfig
|
|
parameters:
|
|
- name: remove_masked
|
|
in: query
|
|
description: |
|
|
Remove masked values from the exported configuration.
|
|
|
|
__Minimum server version__: 10.4.0
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: remove_defaults
|
|
in: query
|
|
description: |
|
|
Remove default values from the exported configuration.
|
|
|
|
__Minimum server version__: 10.4.0
|
|
required: false
|
|
schema:
|
|
type: string
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Configuration retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
put:
|
|
tags:
|
|
- system
|
|
summary: Update configuration
|
|
description: >
|
|
Submit a new configuration for the server to use. As of server version
|
|
4.8, the `PluginSettings.EnableUploads` setting cannot be modified by
|
|
this endpoint.
|
|
|
|
Note that the parameters that aren't set in the configuration that you
|
|
provide will be reset to default values. Therefore, if you want to
|
|
change a configuration parameter and leave the other ones unchanged,
|
|
you need to get the existing configuration first, change the field that
|
|
you want, then put that new configuration.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: UpdateConfig
|
|
requestBody:
|
|
description: Mattermost configuration
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
responses:
|
|
"200":
|
|
description: Configuration update successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/config/reload:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Reload configuration
|
|
description: |
|
|
Reload the configuration file to pick up on any changes made to it.
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: ReloadConfig
|
|
responses:
|
|
"200":
|
|
description: Configuration reload successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/config/migrate:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Migrate config storage
|
|
description: |
|
|
Migrate configuration between storage backends.
|
|
This endpoint is only exposed over a local socket.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: MigrateConfig
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- from
|
|
- to
|
|
properties:
|
|
from:
|
|
type: string
|
|
description: Source config store name.
|
|
to:
|
|
type: string
|
|
description: Destination config store name.
|
|
responses:
|
|
"200":
|
|
description: Config migration successful
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/config/client:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get client configuration
|
|
description: |
|
|
Get a subset of the server configuration needed by the client.
|
|
##### Permissions
|
|
No permission required.
|
|
operationId: GetClientConfig
|
|
responses:
|
|
"200":
|
|
description: Configuration retrieval successful
|
|
/api/v4/config/environment:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get configuration made through environment variables
|
|
description: >
|
|
Retrieve a json object mirroring the server configuration where fields
|
|
are set to true
|
|
|
|
if the corresponding config setting is set through an environment variable. Settings
|
|
|
|
that haven't been set through environment variables will be missing from the object.
|
|
|
|
|
|
__Minimum server version__: 4.10
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetEnvironmentConfig
|
|
responses:
|
|
"200":
|
|
description: Configuration retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/EnvironmentConfig"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/config/patch:
|
|
put:
|
|
tags:
|
|
- system
|
|
summary: Patch configuration
|
|
description: >
|
|
Submit configuration to patch. As of server version 4.8, the
|
|
`PluginSettings.EnableUploads` setting cannot be modified by this
|
|
endpoint.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
|
|
__Minimum server version__: 5.20
|
|
|
|
##### Note
|
|
|
|
The Plugins are stored as a map, and since a map may recursively go
|
|
down to any depth, individual fields of a map are not changed.
|
|
Consider using the `update config` (PUT api/v4/config) endpoint
|
|
to update a plugins configurations.
|
|
operationId: PatchConfig
|
|
requestBody:
|
|
description: Mattermost configuration
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
responses:
|
|
"200":
|
|
description: Configuration update successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Config"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/license:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Upload license file
|
|
description: |
|
|
Upload a license to enable enterprise features.
|
|
|
|
__Minimum server version__: 4.0
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: UploadLicenseFile
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
license:
|
|
description: The license to be uploaded
|
|
type: string
|
|
format: binary
|
|
required:
|
|
- license
|
|
responses:
|
|
"201":
|
|
description: License file 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"
|
|
delete:
|
|
tags:
|
|
- system
|
|
summary: Remove license file
|
|
description: >
|
|
Remove the license file from the server. This will disable all
|
|
enterprise features.
|
|
|
|
|
|
__Minimum server version__: 4.0
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: RemoveLicenseFile
|
|
responses:
|
|
"200":
|
|
description: License removal successful
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/license/client:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get client license
|
|
description: >
|
|
Get a subset of the server license needed by the client.
|
|
|
|
##### Permissions
|
|
|
|
No permission required but having the `manage_system` permission returns more information.
|
|
operationId: GetClientLicense
|
|
parameters:
|
|
- name: format
|
|
in: query
|
|
required: true
|
|
description: Must be `old`, other formats not implemented yet
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: License retrieval successful
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
/api/v4/license/load_metric:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get license load metric
|
|
description: >
|
|
Get the current license load metric, calculated based on monthly active users
|
|
against the licensed user count. Returns a value of 0 when there is no license loaded or
|
|
the license doesn't have a user count.
|
|
|
|
__Minimum server version__: 10.8
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: GetLicenseLoadMetric
|
|
responses:
|
|
"200":
|
|
description: License load metric retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
load:
|
|
type: integer
|
|
description: Current license load metric as an integer
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/trial-license:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Request and install a trial license for your server
|
|
description: >
|
|
Request and install a trial license for your server
|
|
|
|
__Minimum server version__: 5.25
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: RequestTrialLicense
|
|
requestBody:
|
|
description: License request
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- users
|
|
properties:
|
|
users:
|
|
type: integer
|
|
description: Number of users requested (20% extra is going to be added)
|
|
responses:
|
|
"200":
|
|
description: Trial license obtained and installed
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/trial-license/prev:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get last trial license used
|
|
operationId: GetPrevTrialLicense
|
|
description: >
|
|
Get the last trial license used on the server
|
|
|
|
__Minimum server version__: 5.36
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
responses:
|
|
"200":
|
|
description: License fetched successfully.
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/audits:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get audits
|
|
description: >
|
|
Get a page of audits for all users on the system, selected with `page`
|
|
and `per_page` query parameters.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetAudits
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of audits per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
responses:
|
|
"200":
|
|
description: Audits retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Audit"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/caches/invalidate:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Invalidate all the caches
|
|
description: >
|
|
Purge all the in-memory caches for the Mattermost server. This can have
|
|
a temporary negative effect on performance while the caches are
|
|
re-populated.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: InvalidateCaches
|
|
responses:
|
|
"200":
|
|
description: Caches invalidate successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/logs:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get logs
|
|
description: >
|
|
Get a page of server logs, selected with `page` and `logs_per_page`
|
|
query parameters.
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetLogs
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: logs_per_page
|
|
in: query
|
|
description: The number of logs per page. There is a maximum limit of 10000 logs
|
|
per page.
|
|
schema:
|
|
type: string
|
|
default: "10000"
|
|
responses:
|
|
"200":
|
|
description: Logs retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Add log message
|
|
description: >
|
|
Add log messages to the server logs.
|
|
|
|
##### Permissions
|
|
|
|
Users with `manage_system` permission can log ERROR or DEBUG messages.
|
|
|
|
Logged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` or just DEBUG messages when `false`.
|
|
|
|
Non-logged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` and cannot log when `false`.
|
|
operationId: PostLog
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- level
|
|
- message
|
|
properties:
|
|
level:
|
|
type: string
|
|
description: The error level, ERROR or DEBUG
|
|
message:
|
|
type: string
|
|
description: Message to send to the server logs
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Logs sent successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
items:
|
|
type: string
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/logs/query:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Query server logs with filters
|
|
description: >
|
|
Query server logs using filter criteria.
|
|
|
|
##### Permissions
|
|
Must have `get_logs` permission.
|
|
operationId: QueryLogs
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: logs_per_page
|
|
in: query
|
|
description: The number of logs per page.
|
|
schema:
|
|
type: string
|
|
default: "10000"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
server_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
log_levels:
|
|
type: array
|
|
items:
|
|
type: string
|
|
date_from:
|
|
type: string
|
|
description: >
|
|
Inclusive start of the time range. The server parses this using the layout
|
|
`YYYY-MM-DD HH:MM:SS.mmm ±HH:MM` (milliseconds optional; timezone offset required),
|
|
matching Go reference time `2006-01-02 15:04:05.999 -07:00`.
|
|
example: "2024-01-15 14:30:45.123 -05:00"
|
|
date_to:
|
|
type: string
|
|
description: >
|
|
Inclusive end of the time range. Same format as `date_from`
|
|
(`YYYY-MM-DD HH:MM:SS.mmm ±HH:MM`, e.g. `2006-01-02 15:04:05.999 -07:00`).
|
|
example: "2024-01-15 14:30:45.123 -05:00"
|
|
responses:
|
|
"200":
|
|
description: Log query successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: object
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/analytics/old:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get analytics
|
|
description: >
|
|
Get some analytics data about the system. This endpoint uses the old
|
|
format, the `/analytics` route is reserved for the new format when it
|
|
gets implemented.
|
|
|
|
|
|
The returned JSON changes based on the `name` query parameter but is always key/value pairs.
|
|
|
|
|
|
__Minimum server version__: 4.0
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetAnalyticsOld
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
required: false
|
|
description: Possible values are "standard", "bot_post_counts_day",
|
|
"post_counts_day", "user_counts_with_posts_day" or "extra_counts"
|
|
schema:
|
|
type: string
|
|
default: standard
|
|
- name: team_id
|
|
in: query
|
|
required: false
|
|
description: The team ID to filter the data by
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Analytics retrieval successful
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/latest_version:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get latest public server release information
|
|
description: >
|
|
Retrieves metadata about the latest Mattermost server release from GitHub.
|
|
|
|
##### Permissions
|
|
Must have `manage_system` permission.
|
|
operationId: GetLatestVersion
|
|
responses:
|
|
"200":
|
|
description: Latest release metadata retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
tag_name:
|
|
type: string
|
|
name:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
published_at:
|
|
type: string
|
|
body:
|
|
type: string
|
|
html_url:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/system/schema/version:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get applied database schema migrations
|
|
description: >
|
|
Returns the list of applied database schema migrations.
|
|
|
|
##### Permissions
|
|
Must have at least one sysconsole read permission.
|
|
operationId: GetAppliedSchemaMigrations
|
|
responses:
|
|
"200":
|
|
description: Applied schema migrations retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"500":
|
|
$ref: "#/components/responses/InternalServerError"
|
|
/api/v4/server_busy:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Set the server busy (high load) flag
|
|
description: >
|
|
Marks the server as currently having high load which disables
|
|
non-critical services such as search, statuses and typing notifications.
|
|
|
|
|
|
__Minimum server version__: 5.20
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: SetServerBusy
|
|
parameters:
|
|
- name: seconds
|
|
in: query
|
|
required: false
|
|
description: Number of seconds until server is automatically marked as not busy.
|
|
schema:
|
|
type: string
|
|
default: "3600"
|
|
responses:
|
|
"200":
|
|
description: Server busy flag set successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get server busy expiry time.
|
|
description: >
|
|
Gets the timestamp corresponding to when the server busy flag will be
|
|
automatically cleared.
|
|
|
|
|
|
__Minimum server version__: 5.20
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: GetServerBusyExpires
|
|
responses:
|
|
"200":
|
|
description: Server busy expires timestamp retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Server_Busy"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
delete:
|
|
tags:
|
|
- system
|
|
summary: Clears the server busy (high load) flag
|
|
description: >
|
|
Marks the server as not having high load which re-enables non-critical
|
|
services such as search, statuses and typing notifications.
|
|
|
|
|
|
__Minimum server version__: 5.20
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: ClearServerBusy
|
|
responses:
|
|
"200":
|
|
description: Server busy flag cleared successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/notifications/ack:
|
|
post:
|
|
tags:
|
|
- root
|
|
summary: Acknowledge receiving of a notification
|
|
description: >
|
|
__Minimum server version__: 3.10
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: AcknowledgeNotification
|
|
responses:
|
|
"200":
|
|
description: Status of the system
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushNotification"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
/api/v4/redirect_location:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get redirect location
|
|
description: >
|
|
__Minimum server version__: 3.10
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: GetRedirectLocation
|
|
parameters:
|
|
- name: url
|
|
in: query
|
|
required: true
|
|
description: Url to check
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Got redirect location
|
|
content:
|
|
image/*:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
location:
|
|
type: string
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
/api/v4/image:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get an image by url
|
|
description: >
|
|
Fetches an image via Mattermost image proxy.
|
|
|
|
__Minimum server version__: 3.10
|
|
|
|
##### Permissions
|
|
|
|
Must be logged in.
|
|
operationId: GetImageByUrl
|
|
responses:
|
|
"200":
|
|
description: Image found
|
|
content:
|
|
image/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/api/v4/upgrade_to_enterprise:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Executes an inplace upgrade from Team Edition to Enterprise Edition
|
|
description: >
|
|
It downloads the Mattermost Enterprise Edition of your current version
|
|
and replace your current version with it. After the upgrade you need to
|
|
restart the Mattermost server.
|
|
|
|
__Minimum server version__: 5.27
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: UpgradeToEnterprise
|
|
responses:
|
|
"202":
|
|
description: Upgrade started
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushNotification"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"429":
|
|
$ref: "#/components/responses/TooManyRequests"
|
|
|
|
/api/v4/upgrade_to_enterprise/status:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Get the current status for the inplace upgrade from Team Edition to Enterprise Edition
|
|
description: >
|
|
It returns the percentage of completion of the current upgrade or the
|
|
error if there is any.
|
|
|
|
__Minimum server version__: 5.27
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: UpgradeToEnterpriseStatus
|
|
responses:
|
|
"200":
|
|
description: Upgrade status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
percentage:
|
|
type: integer
|
|
description: Current percentage of the upgrade
|
|
error:
|
|
type: string
|
|
description: Error happened during the upgrade
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
|
|
/api/v4/upgrade_to_enterprise/allowed:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Check if the user is allowed to upgrade to Enterprise Edition
|
|
description: >
|
|
Check if the user is allowed to upgrade to Enterprise Edition
|
|
operationId: IsAllowedToUpgradeToEnterprise
|
|
responses:
|
|
"200":
|
|
description: User is allowed to upgrade to Enterprise Edition
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
|
|
/api/v4/restart:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Restart the system after an upgrade from Team Edition to Enterprise Edition
|
|
description: >
|
|
It restarts the current running mattermost instance to execute the new
|
|
Enterprise binary.
|
|
|
|
__Minimum server version__: 5.27
|
|
|
|
##### Permissions
|
|
|
|
Must have `manage_system` permission.
|
|
operationId: RestartServer
|
|
responses:
|
|
"200":
|
|
description: Restart started
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
/api/v4/integrity:
|
|
post:
|
|
tags:
|
|
- system
|
|
summary: Perform a database integrity check
|
|
description: |
|
|
Performs a database integrity check.
|
|
|
|
|
|
__Note__: This check may temporarily harm system performance.
|
|
|
|
|
|
__Minimum server version__: 5.28.0
|
|
|
|
|
|
__Local mode only__: This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).
|
|
operationId: CheckIntegrity
|
|
responses:
|
|
"200":
|
|
description: Integrity check successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/IntegrityCheckResult"
|
|
/api/v4/system/support_packet:
|
|
get:
|
|
tags:
|
|
- system
|
|
summary: Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance.
|
|
description: |
|
|
Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance.
|
|
__Minimum server version: 5.32__
|
|
##### Permissions
|
|
Must have any of the system console read permissions.
|
|
##### License
|
|
Requires either a E10 or E20 license.
|
|
operationId: GenerateSupportPacket
|
|
parameters:
|
|
- name: basic_server_logs
|
|
in: query
|
|
description: |
|
|
Specifies whether the server should include or exclude log files. Default value is true.
|
|
|
|
__Minimum server version__: 9.8.0
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
- name: plugin_packets
|
|
in: query
|
|
description: |
|
|
Specifies plugin identifiers whose content should be included in the Support Packet.
|
|
|
|
__Minimum server version__: 9.8.0
|
|
required: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|