# 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 Capabiltiies 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"]
            additionalProperties:
              type: object
              description: |-
                The custom capabilities the server supports, using the
                Java package naming convention.
            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