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": "definitions/room_event.yaml" 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": "definitions/event.yaml" 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"] 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: |- A list of the most recent messages for this room. This array will consist of at most ``limit`` elements. items: type: object title: RoomEvent allOf: - "$ref": "definitions/room_event.yaml" required: ["start", "end", "chunk"] state: type: array description: |- A list of state events representing the current state of the room. items: title: StateEvent type: object allOf: - "$ref": "definitions/state_event.yaml" 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": "definitions/event.yaml" 404: description: The event was not found or you do not have permission to read this event.