You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/api/client-server/v1/search.yaml

147 lines
5.2 KiB
YAML

swagger: '2.0'
info:
title: "Matrix Client-Server v1 Search API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
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 v2 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": "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",
"user_id": "@test:localhost"
}
}
}
}
}
}
400:
description: Part of the request was invalid.
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"