swagger: '2.0' info: title: "Matrix Client-Server v1 Sync 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: "/events": get: summary: Listen on the event stream. description: |- This will listen for new events and return them to the caller. This will block until an event is received, or until the ``timeout`` is reached. security: - accessToken: [] parameters: - in: query type: string name: from description: The token to stream from. required: false x-example: "s3456_9_0" - in: query type: integer name: timeout description: The maximum time in milliseconds to wait for an event. required: false x-example: "35000" responses: 200: description: "The events received, which may be none." examples: application/json: |- { "start": "s3456_9_0", "end": "s3457_9_0", "chunk": [ { "age": 32, "content": { "body": "incoming message", "msgtype": "m.text" }, "event_id": "$14328055551tzaee:localhost", "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", "user_id": "@bob:localhost" } ] } schema: type: object 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: "An array of events." items: type: object title: RoomEvent allOf: - "$ref": "core-event-schema/room_event.json" 400: description: "Bad pagination ``from`` parameter." "/initialSync": get: summary: Get the user's current state. description: |- This returns the full state for this user, with an optional limit on the number of messages per room to return. security: - accessToken: [] parameters: - in: query type: integer name: limit description: The maximum number of messages to return for each room. required: false x-example: "2" responses: 200: description: The user's current state. examples: application/json: |- { "end": "s3456_9_0", "presence": [ { "content": { "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", "displayname": "Bob", "last_active_ago": 31053, "presence": "online", "user_id": "@bob:localhost" }, "type": "m.presence" } ], "rooms": [ { "membership": "join", "messages": { "chunk": [ { "age": 343513403, "content": { "body": "foo", "msgtype": "m.text" }, "event_id": "$14328044851tzTJS:localhost", "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", "user_id": "@alice:localhost" }, { "age": 343511809, "content": { "body": "bar", "msgtype": "m.text" }, "event_id": "$14328044872spjFg:localhost", "origin_server_ts": 1432804487480, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", "user_id": "@bob:localhost" } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state": [ { "age": 7148266897, "content": { "join_rule": "public" }, "event_id": "$14259997323TLwtb:localhost", "origin_server_ts": 1425999732392, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.join_rules", "user_id": "@alice:localhost" }, { "age": 6547561012, "content": { "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto", "displayname": null, "membership": "join" }, "event_id": "$1426600438280zExKY:localhost", "membership": "join", "origin_server_ts": 1426600438277, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "@alice:localhost", "type": "m.room.member", "user_id": "@alice:localhost" }, { "age": 7148267200, "content": { "creator": "@alice:localhost" }, "event_id": "$14259997320KhbwJ:localhost", "origin_server_ts": 1425999732089, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.create", "user_id": "@alice:localhost" }, { "age": 1622568720, "content": { "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", "displayname": "Bob", "membership": "join" }, "event_id": "$1431525430134MxlLX:localhost", "origin_server_ts": 1431525430569, "replaces_state": "$142652023736BSXcM:localhost", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "@bob:localhost", "type": "m.room.member", "user_id": "@bob:localhost" }, { "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:localhost": 100 }, "users_default": 0 }, "event_id": "$14259997322mqfaq:localhost", "origin_server_ts": 1425999732285, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.power_levels", "user_id": "@alice:localhost" } ], "visibility": "private" } ] } schema: type: object properties: end: type: string description: |- A token which correlates to the last value in ``chunk``. This token should be used with the ``/events`` API to listen for new events. presence: type: array description: A list of presence events. items: type: object title: Event allOf: - "$ref": "core-event-schema/event.json" rooms: type: array items: type: object title: RoomInfo 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"] invite: type: object description: "The invite event if `membership` is `invite`" allOf: - "$ref": "room.room.member" 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": "core-event-schema/room_event.json" 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": "core-event-schema/state_event.json" visibility: type: string enum: ["private", "public"] description: |- Whether this room is visible to the ``/publicRooms`` API or not." required: ["room_id", "membership"] required: ["end", "rooms", "presence"] 404: description: There is no avatar URL for this user or this user does not exist. "/events/{eventId}": get: summary: Get a single event by event ID. description: |- Get a single event based on ``event_id``. You must have permission to retrieve this event e.g. by being a member in the room for this event. security: - accessToken: [] parameters: - in: path type: string name: eventId description: The event ID to get. required: true x-example: "$asfDuShaf7Gafaw:matrix.org" responses: 200: description: The full event. examples: application/json: |- { "content": { "body": "Hello world!", "msgtype": "m.text" }, "room_id:": "!wfgy43Sg4a:matrix.org", "user_id": "@bob:matrix.org", "event_id": "$asfDuShaf7Gafaw:matrix.org", "type": "m.room.message" } schema: allOf: - "$ref": "core-event-schema/event.json" 404: description: The event was not found or you do not have permission to read this event.