mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-01-26 09:03:42 +01:00
1bc0f63bfb
The homeserver can implement its own algorithm, but is suggested to ensure the requesting user can reasonably see the other users. The text is intentionally left vague for whether or not the API is local users only to give the homeserver some flexibility in this area. General cleanup is also included in this commit. Fixes https://github.com/matrix-org/matrix-doc/issues/1108
106 lines
3.5 KiB
YAML
106 lines
3.5 KiB
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.
|
|
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
|