matrix-spec-proposals/data/api/client-server/search.yaml

# 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
          required: true
          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`_.
                        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"]
      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