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

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.