# 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. 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" 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`_. order_by: title: "Ordering" type: string enum: ["recent", "rank"] description: "The order in which to search for results." event_context: title: "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. after_limit: type: integer title: "After limit" description: |- How many events after the result are returned. 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. 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: Categories description: Describes which categories to search in and their criteria. properties: room_events: type: object title: Room Event Results description: Mapping of category name to search criteria. properties: count: type: number description: An approximate count of the total number of results found. 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. 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``. additionalProperties: type: array title: Room State items: "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml" groups: type: object title: Groups description: Any groups that were requested. 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" ] } } }, "next_batch": "5FdgFsd234dfgsdfFD", "count": 1224, "results": [ { "rank": 0.00424866, "result": { "age": 526228296, "content": { "body": "Test content martians and men", "msgtype": "m.text" }, "event_id": "$144429830826TWwbB:localhost", "origin_server_ts": 1444298308034, "room_id": "!qPewotXpIctQySfjSy:localhost", "type": "m.room.message", "sender": "@test:localhost" } } ] } } } 400: description: Part of the request was invalid. 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Search