# 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server User Directory API
  version: 1.0.0
paths:
  /user_directory/search:
    post:
      summary: Searches the user directory.
      description: |-
        Performs a search for users. The homeserver may determine which
        subset of users are searched. However, the homeserver MUST at a
        minimum consider users who are visible to the requester based
        on their membership in rooms known to the homeserver. This means:

        -   users that share a room with the requesting user
        -   users who are joined to rooms known to the homeserver that have a
            `public` [join rule](#mroomjoin_rules)
        -   users who are joined to rooms known to the homeserver that have a
            `world_readable` [history visibility](#room-history-visibility)
        
        The search MUST consider local users to the homeserver, and SHOULD
        query remote users as part of the search.

        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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search_term:
                  type: string
                  description: The term to search for
                  example: foo
                limit:
                  type: integer
                  description: The maximum number of results to return. Defaults to 10.
                  example: 10
              required:
                - search_term
        required: true
      responses:
        "200":
          description: The results of the search.
          content:
            application/json:
              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
                          format: uri
                          example: mxc://bar.com/foo
                          description: The avatar url, as an [`mxc://`
                            URI](/client-server-api/#matrix-content-mxc-uris),
                            if one exists.
                  limited:
                    type: boolean
                    description: Indicates if the result list has been truncated by the limit.
              examples:
                response:
                  value: {
                    "results": [
                      {
                        "user_id": "@foo:bar.com",
                        "display_name": "Foo",
                        "avatar_url": "mxc://bar.com/foo"
                      }
                    ],
                    "limited": false
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - User directory
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer