# 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 sync API" version: "1.0.0" host: localhost:8008 schemes: - https basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: - application/json securityDefinitions: $ref: definitions/security.yaml paths: "/sync": get: summary: Synchronise the client's state and receive new messages. description: |- Synchronise the client's state with the latest state on the server. Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages. operationId: sync security: - accessToken: [] parameters: - in: query name: filter type: string description: |- The ID of a filter created using the filter API or a filter JSON object encoded as a string. The server will detect whether it is an ID or a JSON object by whether the first character is a ``"{"`` open brace. Passing the JSON inline is best suited to one off requests. Creating a filter using the filter API is recommended for clients that reuse the same filter multiple times, for example in long poll requests. x-example: "66696p746572" - in: query name: since type: string description: |- A point in time to continue a sync from. x-example: "s72594_4483_1934" - in: query name: full_state type: boolean description: |- Controls whether to include the full state for all rooms the user is a member of. If this is set to ``true``, then all state events will be returned, even if ``since`` is non-empty. The timeline will still be limited by the ``since`` parameter. In this case, the ``timeout`` parameter will be ignored and the query will return immediately, possibly with an empty timeline. If ``false``, and ``since`` is non-empty, only state which has changed since the point indicated by ``since`` will be returned. By default, this is ``false``. x-example: "false" - in: query name: set_presence type: string enum: ["offline", "online", "unavailable"] description: |- Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is automatically marked as online when it uses this API. Otherwise if the parameter is set to "offline" then the client is not marked as being online when it uses this API. When set to "unavailable", the client is marked as being idle. x-example: "offline" - in: query name: timeout type: integer description: |- The maximum time to wait, in milliseconds, before returning this request. If no events (or other data) become available before this time elapses, the server will return a response with empty fields. By default, this is ``0``, so the server will return immediately even if the response is empty. x-example: 30000 responses: 200: description: The initial snapshot or delta for the client to use to update their state. schema: type: object properties: next_batch: type: string description: |- The batch token to supply in the ``since`` param of the next ``/sync`` request. rooms: title: Rooms type: object description: |- Updates to rooms. properties: join: title: Joined Rooms type: object description: |- The rooms that the user has joined. additionalProperties: title: Joined Room type: object properties: state: title: State type: object description: |- Updates to the state, between the time indicated by the ``since`` parameter, and the start of the ``timeline`` (or all state up to the start of the ``timeline``, if ``since`` is not given, or ``full_state`` is true). N.B. state updates for ``m.room.member`` events will be incomplete if ``lazy_load_members`` is enabled in the ``/sync`` filter, and only return the member events required to display the senders of the timeline events in this response. allOf: - $ref: "definitions/state_event_batch.yaml" timeline: title: Timeline type: object description: |- The timeline of messages and state changes in the room. allOf: - $ref: "definitions/timeline_batch.yaml" ephemeral: title: Ephemeral type: object description: |- The ephemeral events in the room that aren't recorded in the timeline or state of the room. e.g. typing. allOf: - $ref: "definitions/event_batch.yaml" account_data: title: Account Data type: object description: |- The private data that this user has attached to this room. allOf: - $ref: "definitions/event_batch.yaml" "unread_notifications": title: Unread Notification Counts type: object description: |- Counts of unread notifications for this room properties: highlight_count: title: Highlighted notification count type: integer description: The number of unread notifications for this room with the highlight flag set notification_count: title: Total notification count type: integer description: The total number of unread notifications for this room invite: title: Invited Rooms type: object description: |- The rooms that the user has been invited to. additionalProperties: title: Invited Room type: object properties: invite_state: title: InviteState type: object description: |- The state of a room that the user has been invited to. These state events may only have the ``sender``, ``type``, ``state_key`` and ``content`` keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. Instead the client should keep two separate copies of the state: the one from the ``invite_state`` and one from the archived ``state``. If the client joins the room then the current state will be given as a delta against the archived ``state`` not the ``invite_state``. properties: events: description: The StrippedState events that form the invite state. items: description: |- A stripped down state event, with only the ``type``, ``state_key``, ``sender``, and ``content`` keys. properties: content: description: The ``content`` for the event. title: EventContent type: object state_key: description: The ``state_key`` for the event. type: string type: description: The ``type`` for the event. type: string sender: description: The ``sender`` for the event. type: string required: - type - state_key - content - sender title: StrippedState type: object type: array leave: title: Left rooms type: object description: |- The rooms that the user has left or been banned from. additionalProperties: title: Left Room type: object properties: state: title: State type: object description: |- The state updates for the room up to the start of the timeline. allOf: - $ref: "definitions/state_event_batch.yaml" timeline: title: Timeline type: object description: |- The timeline of messages and state changes in the room up to the point when the user left. allOf: - $ref: "definitions/timeline_batch.yaml" account_data: title: Account Data type: object description: |- The private data that this user has attached to this room. allOf: - $ref: "definitions/event_batch.yaml" presence: title: Presence type: object description: |- The updates to the presence status of other users. allOf: - $ref: "definitions/event_batch.yaml" account_data: title: Account Data type: object description: |- The global private data created by this user. allOf: - $ref: "definitions/event_batch.yaml" to_device: title: ToDevice type: object description: |- Information on the send-to-device messages for the client device, as defined in |send_to_device_sync|_. device_lists: title: DeviceLists type: object description: |- Information on end-to-end device updates, as specified in |device_lists_sync|_. device_one_time_keys_count: title: One-time keys count type: object additionalProperties: type: integer description: |- Information on end-to-end encryption keys, as specified in |device_lists_sync|_. required: - next_batch examples: application/json: { "next_batch": "s72595_4483_1934", "presence": { "events": [ {"$ref": "definitions/event-schemas/examples/m.presence"} ] }, "account_data": { "events": [ { "type": "org.example.custom.config", "content": { "custom_config_key": "custom_config_value" } } ] }, "rooms": { "join": { "!726s6s6q:example.com": { "state": { "events": [ { "room_id": "!726s6s6q:example.com", "$ref": "definitions/event-schemas/examples/m.room.member" } ] }, "timeline": { "events": [ { "room_id": "!726s6s6q:example.com", "$ref": "definitions/event-schemas/examples/m.room.member" }, { "room_id": "!726s6s6q:example.com", "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } ], "limited": true, "prev_batch": "t34-23535_0_0" }, "ephemeral": { "events": [ {"$ref": "definitions/event-schemas/examples/m.typing"} ] }, "account_data": { "events": [ {"$ref": "definitions/event-schemas/examples/m.tag"}, { "type": "org.example.custom.room.config", "content": { "custom_config_key": "custom_config_value" } } ] } } }, "invite": { "!696r7674:example.com": { "invite_state": { "events": [ { "sender": "@alice:example.com", "type": "m.room.name", "state_key": "", "content": {"name": "My Room Name"} }, { "sender": "@alice:example.com", "type": "m.room.member", "state_key": "@bob:example.com", "content": {"membership": "invite"} } ] } } }, "leave": {} } } tags: - Room participation