|
|
|
|
# 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 `string` key is the user ID for which
|
|
|
|
|
the profile belongs to.
|
|
|
|
|
additionalProperties:
|
|
|
|
|
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 `string` key is the room ID for which the `State
|
|
|
|
|
Event` array belongs to.
|
|
|
|
|
additionalProperties:
|
|
|
|
|
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
|
