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}/state/{eventType}/{stateKey}": get: summary: Get the state identified by the type and key. description: |- Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left. security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room to look up the state in. required: true x-example: "!636q39766251:example.com" - in: path type: string name: eventType description: The type of state to look up. required: true x-example: "m.room.name" - in: path type: string name: stateKey description: The key of the state to look up. required: true x-example: "" responses: 200: description: The content of the state event. examples: application/json: |- {"name": "Example room name"} schema: type: object 404: description: The room has no state with the given type or key. 403: description: > You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/state/{eventType}": get: summary: Get the state identified by the type, with the empty state key. description: |- Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left. This looks up the state event with the empty state key. security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room to look up the state in. required: true x-example: "!636q39766251:example.com" - in: path type: string name: eventType description: The type of state to look up. required: true x-example: "m.room.name" responses: 200: description: The content of the state event. examples: application/json: |- {"name": "Example room name"} schema: type: object 404: description: The room has no state with the given type or key. 403: description: > You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/state": get: summary: Get all state events in the current state of a room. description: |- Get the state events for the current state of a room. security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room to look up the state for. required: true x-example: "!636q39766251:example.com" responses: 200: description: The current state of the room examples: application/json: |- [ { "age": 7148266897, "content": { "join_rule": "public" }, "event_id": "$14259997323TLwtb:example.com", "origin_server_ts": 1425999732392, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.join_rules", "sender": "@alice:example.com" }, { "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", "membership": "join", "origin_server_ts": 1426600438277, "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", "sender": "@alice:example.com" }, { "age": 7148267200, "content": { "creator": "@alice:example.com" }, "event_id": "$14259997320KhbwJ:example.com", "origin_server_ts": 1425999732089, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.create", "sender": "@alice:example.com" }, { "age": 1622568720, "content": { "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", "displayname": "Bob", "membership": "join" }, "event_id": "$1431525430134MxlLX:example.com", "origin_server_ts": 1431525430569, "replaces_state": "$142652023736BSXcM:example.com", "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", "sender": "@bob:example.com" }, { "age": 7148267004, "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "kick": 50, "redact": 50, "state_default": 50, "users": { "@alice:example.com": 100 }, "users_default": 0 }, "event_id": "$14259997322mqfaq:example.com", "origin_server_ts": 1425999732285, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.power_levels", "sender": "@alice:example.com" } ] schema: type: array title: RoomState description: |- If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room then this will be the state of the room when they left as a list of events. items: title: StateEvent type: object allOf: - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" 403: description: > You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/initialSync": get: summary: Snapshot the current state of a room and its most recent messages. description: |- Get a copy of the current state and the most recent messages in a room. security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room to get the data. required: true x-example: "!636q39766251:example.com" responses: 200: description: The current state of the room examples: application/json: |- { "membership": "join", "messages": { "chunk": [ { "age": 343513403, "content": { "body": "foo", "msgtype": "m.text" }, "event_id": "$14328044851tzTJS:example.com", "origin_server_ts": 1432804485886, "room_id": "!636q39766251:example.com", "type": "m.room.message", "sender": "@alice:example.com" }, { "age": 343511809, "content": { "body": "bar", "msgtype": "m.text" }, "event_id": "$14328044872spjFg:example.com", "origin_server_ts": 1432804487480, "room_id": "!636q39766251:example.com", "type": "m.room.message", "sender": "@bob:example.com" } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!636q39766251:example.com", "state": [ { "age": 7148266897, "content": { "join_rule": "public" }, "event_id": "$14259997323TLwtb:example.com", "origin_server_ts": 1425999732392, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.join_rules", "sender": "@alice:example.com" }, { "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", "membership": "join", "origin_server_ts": 1426600438277, "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", "sender": "@alice:example.com" }, { "age": 7148267200, "content": { "creator": "@alice:example.com" }, "event_id": "$14259997320KhbwJ:example.com", "origin_server_ts": 1425999732089, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.create", "sender": "@alice:example.com" }, { "age": 1622568720, "content": { "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", "displayname": "Bob", "membership": "join" }, "event_id": "$1431525430134MxlLX:example.com", "origin_server_ts": 1431525430569, "replaces_state": "$142652023736BSXcM:example.com", "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", "sender": "@bob:example.com" }, { "age": 7148267004, "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "kick": 50, "redact": 50, "state_default": 50, "users": { "@alice:example.com": 100 }, "users_default": 0 }, "event_id": "$14259997322mqfaq:example.com", "origin_server_ts": 1425999732285, "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.power_levels", "sender": "@alice:example.com" } ], "visibility": "private", "account_data": [{ "type": "m.tag", "content": {"tags": {"work": {"order": "1"}}} }] } schema: title: RoomInfo type: object properties: room_id: type: string description: "The ID of this room." membership: type: string description: "The user's membership state in this room." enum: ["invite", "join", "leave", "ban"] messages: type: object title: PaginationChunk description: "The pagination chunk for this room." properties: start: type: string description: |- A token which correlates to the first value in ``chunk``. Used for pagination. end: type: string description: |- A token which correlates to the last value in ``chunk``. Used for pagination. chunk: type: array description: |- If the user is a member of the room this will be a list of the most recent messages for this room. If the user has left the room this will be the messages that preceeded them leaving. This array will consist of at most ``limit`` elements. items: type: object title: RoomEvent allOf: - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" required: ["start", "end", "chunk"] state: type: array description: |- If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room this will be the state of the room when they left it. items: title: StateEvent type: object allOf: - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" visibility: type: string enum: ["private", "public"] description: |- Whether this room is visible to the ``/publicRooms`` API or not." account_data: type: array description: |- The private data that this user has attached to this room. items: title: Event type: object allOf: - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" required: ["room_id"] 403: description: > You aren't a member of the room and weren't previously a member of the room. tags: - Room participation deprecated: true "/rooms/{roomId}/members": get: summary: Get the m.room.member events for the room. description: Get the list of members for this room. parameters: - in: path type: string name: roomId description: The room to get the member events for. required: true x-example: "!636q39766251:example.com" responses: 200: description: |- A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left te room then this will be the members of the room when you left. examples: application/json: |- { "chunk": [ { "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", "membership": "join", "origin_server_ts": 1426600438277, "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", "sender": "@alice:example.com" }, { "age": 1622568720, "content": { "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", "displayname": "Bob", "membership": "join" }, "event_id": "$1431525430134MxlLX:example.com", "origin_server_ts": 1431525430569, "replaces_state": "$142652023736BSXcM:example.com", "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", "sender": "@bob:example.com" } ] } schema: type: object properties: chunk: type: array items: title: MemberEvent type: object allOf: - "$ref": "../../event-schemas/schema/m.room.member" 403: description: > You aren't a member of the room and weren't previously a member of the room. tags: - Room participation