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

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:
  accessToken:
    type: apiKey
    description: The user_id or application service access_token
    name: access_token
    in: query
paths:
  "/search":
    post:
      summary: Search server side for things.
      description: |-
        Performs a full text search across different categories.
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: |-
              {
                "search_categories": {
                  "room_events": {
                    "keys": [
                      "content.body"
                    ],
                    "search_term": "martians and men"
                  }
                }
              }
            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
                        description: |-
                            The filter to apply to search results.
                            This has the same format as filter API.
                    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: Total number of results found
                      results:
                        type: object
                        title: Results
                        description: Mapping of event_id to result.
                        additionalProperties:
                          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": "../../event-schemas/schema/core-event-schema/room_event.json"
          examples:
            application/json: |-
               {
                  "search_categories": {
                    "room_events": {
                      "count": 24,
                      "results": {
                        "$144429830826TWwbB:localhost": {
                          "rank": 0.00424866,
                          "result": {
                            "age": 526228296,
                            "content": {
                              "body": "Test content",
                              "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"