matrix-spec/data/api/client-server/versions.yaml

# Copyright 2016 OpenMarket 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server Versions API
  version: 1.0.0
paths:
  /versions:
    get:
      summary: Gets the versions of the specification supported by the server.
      description: |-
        Gets the versions of the specification supported by the server.

        Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See
        [the Specification Versioning](../#specification-versions) for more
        information.

        The server may additionally advertise experimental features it supports
        through `unstable_features`. These features should be namespaced and
        may optionally include version information within their name if desired.
        Features listed here are not for optionally toggling parts of the Matrix
        specification and should only be used to advertise support for a feature
        which has not yet landed in the spec. For example, a feature currently
        undergoing the proposal process may appear here and eventually be taken
        off this list once the feature lands in the spec and the server deems it
        reasonable to do so. Servers can choose to enable some features only for
        some users, so clients should include authentication in the request to
        get all the features available for the logged-in user. If no
        authentication is provided, the server should only return the features
        available to all users. Servers may wish to keep advertising features
        here after they've been released into the spec to give clients a chance
        to upgrade appropriately. Additionally, clients should avoid using
        unstable features in their stable releases.
      operationId: getVersions
      security:
        - {}
        - accessTokenQuery: []
        - accessTokenBearer: []
      x-changedInMatrixVersion:
        "1.10": |
          This endpoint can behave differently when authentication is provided.
      responses:
        "200":
          description: The versions supported by the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    description: The supported versions.
                    items:
                      type: string
                      description: The supported versions
                  unstable_features:
                    type: object
                    description: |-
                      Experimental features the server supports. Features not listed here,
                      or the lack of this property all together, indicate that a feature is
                      not supported.
                    additionalProperties:
                      type: boolean
                      description: Whether or not the namespaced feature is supported.
                required:
                  - versions
              examples:
                response:
                  value: {
                    "versions": [
                      "r0.0.1",
                      "v1.1"
                    ],
                    "unstable_features": {
                      "org.example.my_feature": true
                    }
                  }
      tags:
        - Server administration
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer