You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/search.yaml

386 lines
17 KiB
YAML

# Copyright 2016 OpenMarket 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 Search API
version: 1.0.0
paths:
/search:
post:
summary: Perform a server-side search.
description: Performs a full text search across different categories.
operationId: search
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: next_batch
description: |-
The point to return events from. If given, this should be a
`next_batch` result from a previous call to this endpoint.
example: YWxsCgpOb25lLDM1ODcwOA
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"search_categories": {
"room_events": {
"keys": [
"content.body"
],
"search_term": "martians and men",
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
}
}
}
}
properties:
search_categories:
type: object
title: Categories
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
type: string
description: The string to search events for
keys:
type: array
items:
type: string
enum:
- content.body
- content.name
- content.topic
description: The keys to search. Defaults to all.
filter:
type: object
title: Filter
description: This takes a [filter](/client-server-api/#filtering).
allOf:
- $ref: definitions/room_event_filter.yaml
order_by:
title: Ordering
type: string
enum:
- recent
- rank
description: |-
The order in which to search for results.
By default, this is `"rank"`.
event_context:
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
returned are included in the response.
properties:
before_limit:
type: integer
title: Before limit
description: |-
How many events before the result are
returned. By default, this is `5`.
after_limit:
type: integer
title: After limit
description: |-
How many events after the result are
returned. By default, this is `5`.
include_profile:
type: boolean
title: Return profile information
description: |-
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is `false`.
include_state:
type: boolean
title: Include current state
description: |-
Requests the server return the current state for
each room returned.
groupings:
type: object
title: Groupings
description: |-
Requests that the server partitions the result set
based on the provided list of keys.
properties:
group_by:
type: array
title: Groups
description: List of groups to request.
items:
type: object
title: Group
description: Configuration for group.
properties:
key:
type: string
title: Group Key
description: Key that defines the group.
enum:
- room_id
- sender
required:
- search_term
required:
- search_categories
required: true
responses:
"200":
description: Results of the search.
content:
application/json:
schema:
type: object
title: Results
required:
- search_categories
properties:
search_categories:
type: object
title: Result Categories
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming
which may change the query terms.
items:
type: string
results:
type: array
title: Results
description: List of results in the requested order.
items:
type: object
title: Result
description: The result object.
properties:
rank:
type: number
description: A number that describes how closely this result matches the search.
Higher is closer.
result:
type: object
title: Event
description: The event that matched.
allOf:
- $ref: definitions/client_event.yaml
context:
type: object
title: Event Context
description: Context for result, if requested.
properties:
start:
type: string
title: Start Token
description: Pagination token for the start of the chunk
end:
type: string
title: End Token
description: Pagination token for the end of the chunk
profile_info:
type: object
title: Profile Information
description: |-
The historic profile information of the
users that sent the events returned.
The key is the user ID for which
the profile belongs to.
patternProperties:
"^@":
x-pattern-format: mx-user-id
type: object
title: User Profile
properties:
displayname:
type: string
title: Display name
avatar_url:
type: string
format: uri
title: Avatar Url
events_before:
type: array
title: Events Before
description: Events just before the result.
items:
title: Event
type: object
$ref: definitions/client_event.yaml
events_after:
type: array
title: Events After
description: Events just after the result.
items:
title: Event
type: object
$ref: definitions/client_event.yaml
state:
type: object
title: Current state
description: |-
The current state for every room in the results.
This is included if the request had the
`include_state` key set with a value of `true`.
The key is the room ID for which the `State
Event` array belongs to.
patternProperties:
"^!":
x-pattern-format: mx-room-id
type: array
title: Room State
items:
$ref: definitions/client_event.yaml
groups:
type: object
title: Groups
description: |-
Any groups that were requested.
The outer `string` key is the group key requested (eg: `room_id`
or `sender`). The inner `string` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
description: The results for a given group.
additionalProperties:
type: object
title: Group Value
description: The results for a particular group value.
properties:
next_batch:
type: string
title: Next Batch in Group
description: |-
Token that can be used to get the next batch
of results in the group, by passing as the
`next_batch` parameter to the next call. If
this field is absent, there are no more
results in this group.
order:
type: integer
title: Group Order
description: |-
Key that can be used to order different
groups.
results:
type: array
description: Which results are in this group.
items:
type: string
title: Result Event ID
next_batch:
type: string
title: Next Batch
description: |-
Token that can be used to get the next batch of
results, by passing as the `next_batch` parameter to
the next call. If this field is absent, there are no
more results.
examples:
response:
value: {
"search_categories": {
"room_events": {
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"order": 1,
"next_batch": "BdgFsdfHSf-dsFD",
"results": [
"$144429830826TWwbB:localhost"
]
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [
{
"rank": 0.00424866,
"result": {
"room_id": "!qPewotXpIctQySfjSy:localhost",
"event_id": "$144429830826TWwbB:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
}
]
}
}
}
"400":
description: Part of the request was invalid.
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Search
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