matrix-spec/data/api/server-server/query.yaml

# Copyright 2017 Kamax.io
# Copyright 2018 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.
openapi: 3.1.0
info:
  title: Matrix Federation Query API
  version: 1.0.0
paths:
  "/query/{queryType}":
    get:
      summary: Query for information
      description: |-
        Performs a single query request on the receiving homeserver. The query string
        arguments are dependent on which type of query is being made. Known query types
        are specified as their own endpoints as an extension to this definition.
      operationId: queryInfo
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: queryType
          description: The type of query to make
          required: true
          example: profile
          schema:
            type: string
      responses:
        "200":
          description: The query response. The schema varies depending on the query being
            made.
  /query/directory:
    get:
      summary: Query for the room ID and resident homeservers for a room alias
      description: |-
        Performs a query to get the mapped room ID and list of resident homeservers in
        the room for a given room alias. Homeservers should only query room aliases
        that belong to the target server (identified by the [server name](/appendices/#server-name)
        in the alias).

        Servers may wish to cache the response to this query to avoid requesting the
        information too often.
      operationId: queryRoomDirectory
      security:
        - signedRequest: []
      parameters:
        - in: query
          name: room_alias
          description: The room alias to query.
          required: true
          example: "#room_alias:example.org"
          schema:
            type: string
      responses:
        "200":
          description: The corresponding room ID and list of known resident homeservers
            for the room.
          content:
            application/json:
              schema:
                type: object
                properties:
                  room_id:
                    type: string
                    description: The room ID mapped to the queried room alias.
                    example: "!roomid1234:example.org"
                  servers:
                    type: array
                    description: |-
                      An array of server names that are likely to hold the given room. This
                      list may or may not include the server answering the query.
                    items:
                      type: string
                required:
                  - room_id
                  - servers
              examples:
                response:
                  value: {
                    "room_id": "!roomid1234:example.org",
                    "servers": [
                      "example.org",
                      "example.com",
                      "another.example.com:8449"
                    ]
                  }
        "404":
          description: The room alias was not found.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Room alias not found."
                  }
  /query/profile:
    get:
      summary: Query for profile information about a given user
      description: |-
        Performs a query to get profile information, such as a display name or avatar,
        for a given user. Homeservers should only query profiles for users that belong
        to the target server (identified by the [server name](/appendices/#server-name)
        in the user ID).

        Servers may wish to cache the response to this query to avoid requesting the
        information too often.

        Servers MAY deny profile look-up over federation by responding with 403 and an
        error code of `M_FORBIDDEN`.
      operationId: queryProfile
      security:
        - signedRequest: []
      parameters:
        - in: query
          name: user_id
          description: The user ID to query. Must be a user local to the receiving homeserver.
          required: true
          example: "@someone:example.org"
          schema:
            type: string
        - in: query
          name: field
          description: |-
            The field to query. If specified, the server will only return the given field
            in the response. If not specified, the server will return the full profile for
            the user.
          schema:
            type: string
            enum:
              - displayname
              - avatar_url
      responses:
        "200":
          description: |-
            The profile for the user. If a `field` is specified in the request, only the
            matching field should be included in the response. If no `field` was specified,
            the response should include the fields of the user's profile that can be made
            public, such as the display name and avatar.

            If the user does not have a particular field set on their profile, the server
            should exclude it from the response body or give it the value `null`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  displayname:
                    type: string
                    description: |-
                      The display name of the user. May be omitted if the user does not have a
                      display name set.
                    example: John Doe
                  avatar_url:
                    type: string
                    description: |-
                      The avatar URL for the user's avatar. May be omitted if the user does not
                      have an avatar set.
                    example: mxc://matrix.org/MyC00lAvatar
              examples:
                response:
                  value: {
                    "displayname": "John Doe",
                    "avatar_url": "mxc://matrix.org/MyC00lAvatar"
                  }
        "403":
          x-addedInMatrixVersion: "1.12"
          description: The server is unwilling to disclose whether the user exists and/or
            has profile information.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN",
                    "error": "Profile lookup over federation is disabled on this homeserver"
                  }
        "404":
          description: The user does not exist or does not have a profile.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "User does not exist."
                  }
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8448
      basePath:
        default: /_matrix/federation/v1
components:
  securitySchemes:
    signedRequest:
      $ref: definitions/security.yaml#/signedRequest