# 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 MUST only query profiles for users that belong to the target server (identified by the [server name](/appendices/#server-name) in the user ID). Responding servers MAY: - Allow users to set arbitrary key/value pairs in their profile in addition to the specified pairs. - Deny profile look-up over federation by responding with 403 and an error code of `M_FORBIDDEN`. - Omit certain key/value pairs in the response. Requesting servers MAY wish to cache the response to this query to avoid requesting the information too often. 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 of the profile to query. If specified, the server MUST only return the given field in the response. If not specified, the server MUST return the full, public, profile for the user. Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these servers MAY allow users to set additional key/value pairs. schema: type: string responses: "200": description: |- The profile for the user. If a `field` is specified in the request, the response MUST only included the specified `field`. If no `field` was specified, the response SHOULD include all of the fields of the user's profile, which can be made public. If a field in the user's profile can't be made public over the federation, the responding server MAY choose to exclude it in the response. If the user does not have a particular field set on their profile, the server MUST either 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. MUST either be omitted or set to `null` 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. MUST either be omitted or set to `null` if the user does not have an avatar set. example: mxc://example.org/MyC00lAvatar m.tz: type: string description: The name of the user's time zone. The name SHOULD be registered in the [IANA Time Zone Database](https://www.iana.org/time-zones), requesting servers MUST tolerate invalid or unknown values. x-addedInMatrixVersion: "1.16" additionalProperties: description: Additional profile fields. examples: response: value: { "displayname": "John Doe", "avatar_url": "mxc://example.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, does not have a profile or the queried field does not exist. 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