matrix-spec-proposals/api/client-server/users.yaml

# Copyright 2017 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 User Directory API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/user_directory/search":
    post:
      summary: Searches the user directory.
      description: |-
        Performs a search for users on the homeserver. The homeserver may
        determine which subset of users are searched, however the homeserver
        is encouraged to only consider users the requesting user shares a
        room with and those who reside in public rooms.

        The search is performed case-insensitively on user IDs and display
        names preferably using a collation determined based upon the 
        ``Accept-Language`` header provided in the request, if present.
      operationId: searchUserDirectory
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              search_term:
                type: string
                description: The term to search for
                example: "foo"
              limit:
                type: number
                description: The maximum number of results to return. Defaults to 10.
                example: 10
            required: ["search_term"]
      responses:
        200:
          description: The results of the search.
          examples:
            application/json: {
              "results": [
                {
                  "user_id": "@foo:bar.com",
                  "display_name": "Foo",
                  "avatar_url": "mxc://bar.com/foo"
                }
              ],
              "limited": false
            }
          schema:
            type: object
            required: ["results", "limited"]
            properties:
              results:
                type: array
                description: Ordered by rank and then whether or not profile info is available.
                items:
                  title: User
                  type: object
                  required: ["user_id"]
                  properties:
                    user_id:
                      type: string
                      example: "@foo:bar.com"
                      description: The user's matrix user ID.
                    display_name:
                      type: string
                      example: "Foo"
                      description: The display name of the user, if one exists.
                    avatar_url:
                      type: string
                      example: "mxc://bar.com/foo"
                      description: The avatar url, as an MXC, if one exists.
              limited:
                type: boolean
                description: Indicates if the result list has been truncated by the limit.
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - User data