matrix-spec/api/client-server/sync.yaml

# 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"]
          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.
          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).
                          allOf:
                            - $ref: "definitions/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``.
                          allOf:
                            - $ref: "definitions/event_batch.yaml"
                  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/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|_.
          examples:
            application/json: {
                "next_batch": "s72595_4483_1934",
                "presence": {
                  "events": [
                    {
                      "sender": "@alice:example.com",
                      "type": "m.presence",
                      "content": {"presence": "online"}
                    }
                  ]
                },
                "account_data": {
                  "events": [
                    {
                      "type": "org.example.custom.config",
                      "content": {
                        "custom_config_key": "custom_config_value"
                      }
                    }
                  ]
                },
                "rooms": {
                  "join": {
                    "!726s6s6q:example.com": {
                      "state": {
                        "events": [
                          {
                            "sender": "@alice:example.com",
                            "type": "m.room.member",
                            "state_key": "@alice:example.com",
                            "content": {"membership": "join"},
                            "origin_server_ts": 1417731086795,
                            "event_id": "$66697273743031:example.com"
                          }
                        ]
                      },
                      "timeline": {
                        "events": [
                          {
                            "sender": "@bob:example.com",
                            "type": "m.room.member",
                            "state_key": "@bob:example.com",
                            "content": {"membership": "join"},
                            "prev_content": {"membership": "invite"},
                            "origin_server_ts": 1417731086795,
                            "event_id": "$7365636s6r6432:example.com"
                          },
                          {
                            "sender": "@alice:example.com",
                            "type": "m.room.message",
                            "age": 124524,
                            "txn_id": "1234",
                            "content": {
                              "body": "I am a fish",
                              "msgtype": "m.text"
                            },
                            "origin_server_ts": 1417731086797,
                            "event_id": "$74686972643033:example.com"
                          }
                        ],
                        "limited": true,
                        "prev_batch": "t34-23535_0_0"
                      },
                      "ephemeral": {
                        "events": [
                          {
                            "type": "m.typing",
                            "content": {"user_ids": ["@alice:example.com"]}
                          }
                        ]
                      },
                      "account_data": {
                        "events": [
                          {
                            "type": "m.tag",
                            "content": {"tags": {"work": {"order": 1}}}
                          },
                          {
                            "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