# 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 Rooms 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 :
"/rooms/{roomId}/messages" :
get :
summary : Get a list of events for this room
description : |-
This API returns a list of message and state events for a room. It uses
pagination query parameters to paginate history in the room.
operationId : getRoomEvents
security :
- accessToken : [ ]
parameters :
- in : path
type : string
name : roomId
description : The room to get events from.
required : true
x-example : "!636q39766251:example.com"
- in : query
type : string
name : from
description : |-
The token to start returning events from. This token can be obtained
from a ``prev_batch`` token returned for each room by the sync API,
or from a ``start`` or ``end`` token returned by a previous request
to this endpoint.
required : true
x-example : "s345_678_333"
- in : query
type : string
name : to
description : |-
The token to stop returning events at. This token can be obtained from
a ``prev_batch`` token returned for each room by the sync endpoint,
or from a ``start`` or ``end`` token returned by a previous request to
this endpoint.
required : false
- in : query
type : string
enum : [ "b" , "f" ]
name : dir
description : |-
The direction to return events from.
required : true
x-example : "b"
- in : query
type : integer
name : limit
description : |-
The maximum number of events to return. Default : 10 .
x-example : "3"
- in : query
type : string
name : filter
description : |-
A JSON RoomEventFilter to filter returned events with.
x-example : |-
{"contains_url" : true }
responses :
200 :
description : A list of messages with a new token to request more.
schema :
type : object
description : A list of messages with a new token to request more.
properties :
start :
type : string
description : |-
The token the pagination starts from. If ``dir=b`` this will be
the token supplied in ``from``.
end :
type : string
description : |-
The token the pagination ends at. If ``dir=b`` this token should
be used again to request even earlier events.
chunk :
type : array
description : |-
A list of room events. The order depends on the ``dir`` parameter. For ``dir=b`` events will be in reverse-chronological order, for ``dir=f`` in chronological order, so that events start at the ``from`` point.
items :
type : object
title : RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
examples :
application/json : {
"start": "t47429-4392820_219380_26003_2265" ,
"end": "t47409-4357353_219380_26003_2265" ,
"chunk": [
{
"room_id": "!636q39766251:example.com" ,
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"room_id": "!636q39766251:example.com" ,
"$ref": "definitions/event-schemas/examples/m.room.name"
},
{
"room_id": "!636q39766251:example.com" ,
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
]
}
403 :
description : >
You aren't a member of the room.
tags :
- Room participation