matrix-spec/api/client-server/capabilities.yaml

# Copyright 2019 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
  title: "Matrix Client-Server Capabilities API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/capabilities":
    get:
      summary: Gets information about the server's capabilities.
      description: |-
        Gets information about the server's supported feature set
        and other relevant capabilities.
      operationId: getCapabilities
      security:
        - accessToken: []
      parameters: []
      responses:
        200:
          description:
            The capabilities of the server.
          examples:
            application/json: {
              "capabilities": {
                "m.change_password": {
                  "enabled": false
                },
                "m.room_versions": {
                  "default": "1",
                  "available": {
                    "1": "stable",
                    "2": "stable",
                    "3": "unstable",
                    "test-version": "unstable"
                  }
                },
                "com.example.custom.ratelimit": {
                  "max_requests_per_hour": 600
                }
              }
            }
          schema:
            type: object
            required: ["capabilities"]
            properties:
              capabilities:
                type: object
                title: Capabilities
                description: |-
                    The custom capabilities the server supports, using the
                    Java package naming convention.
                additionalProperties:
                  type: object
                properties:
                  "m.change_password":
                    type: object
                    description: |-
                      Capability to indicate if the user can change their password.
                    title: ChangePasswordCapability
                    properties:
                      enabled:
                        type: boolean
                        description: |-
                          True if the user can change their password, false otherwise.
                        example: false
                    required: ['enabled']
                  "m.room_versions":
                    type: object
                    description: The room versions the server supports.
                    title: RoomVersionsCapability
                    properties:
                      default:
                        type: string
                        description: |-
                          The default room version the server is using for new rooms.
                        example: "1"
                      available:
                        type: object
                        description: |-
                          A detailed description of the room versions the server supports.
                        additionalProperties:
                          type: string
                          title: RoomVersionStability
                          enum: [stable, unstable]
                          description: The stability of the room version.
                    required: ['default', 'available']
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Capabilities