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

swagger: '2.0'
info:
  title: "Matrix Client-Server v2 sync API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
basePath: /_matrix/client/v2_alpha
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:
  "/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.
        Client's 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.
      security:
        - accessToken: []
      parameters:
        - in: query
          name: filter
          type: string
          description: |-
            The ID of a filter created using the filter API.
          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: 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 poll in milliseconds before returning this
            request.
          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:
                  joined:
                    title: Joined
                    type: object
                    additionalProperties:
                      title: Joined Room
                      type: object
                      properties:
                        event_map:
                          title: EventMap
                          type: object
                          description: |-
                            A map from event ID to events for this room. The
                            events are referenced from the ``timeline`` and
                            ``state`` keys for this room.
                          additionalProperties:
                            title: Event
                            description: An event object.
                            type: object
                            allOf:
                              - $ref: "core-event-schema/event.json"
                        state:
                          title: State
                          type: object
                          description: |-
                            The state updates for the room.
                          allOf:
                            - $ref: "definitions/room_event_batch.json"
                        timeline:
                          title: Timeline
                          type: object
                          description: |-
                            The timeline of messages and state changes in the
                            room.
                          allOf:
                            - $ref: "definitions/timeline_batch.json"
                        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.json"
                  invited:
                    title: Invited
                    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.json"
                  archived:
                    title: Archived
                    type: object
                    description: |-
                      The rooms that the user has left or been banned from. The
                      entries in the room_map will lack an ``ephemeral`` key.
                    additionalProperties:
                      title: Archived Room
                      type: object
                      properties:
                        event_map:
                          title: EventMap
                          type: object
                          description: |-
                            A map from event ID to events for this room. The
                            events are referenced from the ``timeline`` and
                            ``state`` keys for this room.
                          additionalProperties:
                            title: Event
                            description: An event object.
                            type: object
                            allOf:
                              - $ref: "core-event-schema/event.json"
                        state:
                          title: State
                          type: object
                          description: |-
                            The state updates for the room up to the point when
                            the user left.
                          allOf:
                            - $ref: "definitions/room_event_batch.json"
                        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.json"
              presence:
                title: Presence
                type: object
                description: |-
                  The updates to the presence status of other users.
                allOf:
                  - $ref: "definitions/event_batch.json"
          examples:
            application/json: |-
              {
                "next_batch": "s72595_4483_1934",
                "presence": {
                  "events": [
                    {
                      "sender": "@alice:example.com",
                      "type": "m.presence",
                      "content": {"presence": "online"}
                    }
                  ]
                },
                "rooms": {
                  "joined": {
                    "!726s6s6q:example.com": {
                      "event_map": {
                        "$66697273743031:example.com": {
                          "sender": "@alice:example.com",
                          "type": "m.room.member",
                          "state_key": "@alice:example.com",
                          "content": {"membership": "join"},
                          "origin_server_ts": 1417731086795
                        },
                        "$7365636s6r6432:example.com": {
                          "sender": "@bob:example.com",
                          "type": "m.room.member",
                          "state_key": "@bob:example.com",
                          "content": {"membership": "join"},
                          "origin_server_ts": 1417731086795
                        },
                        "$74686972643033:example.com": {
                          "sender": "@alice:example.com",
                          "type": "m.room.message",
                          "unsigned": {"age": "124524", "txn_id": "1234"},
                          "content": {
                            "body": "I am a fish",
                            "msgtype": "m.text"
                          },
                          "origin_server_ts": 1417731086797
                        }
                      },
                      "state": {
                        "events": [
                          "$66697273743031:example.com",
                          "$7365636s6r6432:example.com"
                        ]
                      },
                      "timeline": {
                        "events": [
                          "$7365636s6r6432:example.com",
                          "$74686972643033:example.com"
                        ],
                        "limited": true,
                        "prev_batch": "t34-23535_0_0"
                      },
                      "ephemeral": {
                        "events": [
                          {
                            "room_id": "!726s6s6q:example.com",
                            "type": "m.typing",
                            "content": {"user_ids": ["@alice:example.com"]}
                          }
                        ]
                      }
                    }
                  },
                  "invited": {
                    "!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"}
                          }
                        ]
                      }
                    }
                  },
                  "archived": {}
                }
              }