# 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. swagger: '2.0' info: title: "Matrix Client-Server Search 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: "/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 type: string description: |- The point to return events from. If given, this should be a ``next_batch`` result from a previous call to this endpoint. x-example: "YWxsCgpOb25lLDM1ODcwOA" - in: body name: body 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 # Within the C-S spec document, `filter`_ is picked up # as a link to the filtering section. In OpenAPI 3.0, # we could use the link feature, but we're still on 2.0 # for now :/ description: |- This takes a `filter`_. $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"] responses: 200: description: Results of the search. 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. "$ref": "definitions/event-schemas/schema/core-event-schema/room_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 title: Avatar Url events_before: type: array title: Events Before description: Events just before the result. items: title: Event type: object "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml" events_after: type: array title: Events After description: Events just after the result. items: title: Event type: object "$ref": "definitions/event-schemas/schema/core-event-schema/room_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: type: object "$ref": "definitions/event-schemas/schema/core-event-schema/state_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: application/json: { "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": "definitions/event-schemas/examples/m.room.message$m.text" } } ] } } } 400: description: Part of the request was invalid. 429: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - Search