# 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
