# 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: - accessToken: [] 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: $ref: definitions/security.yaml