matrix-spec/api/client-server/old_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. This token is either from a previous
            request to this API or from the initial sync API.
          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``. This
                  is usually the same token supplied to ``from=``.
              end:
                type: string
                description: |-
                  A token which correlates to the last value in ``chunk``. This
                  token should be used in the next request to ``/events``.
              chunk:
                type: array
                description: "An array of events."
                items:
                  type: object
                  title: Event
                  allOf:
                    - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
        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"
        - in: query
          type: boolean
          name: archived
          description: |-
            Whether to include rooms that the user has left. If ``false`` then
            only rooms that the user has been invited to or has joined are
            included. If set to ``true`` then rooms that the user has left are
            included as well. By default this is ``false``.
          required: false
          x-example: "true"
      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"
                      }
                  ],
                  "account_data": [
                    {
                      "type": "org.example.custom.config",
                      "content": {
                        "custom_config_key": "custom_config_value"
                      }
                    }
                  ],
                  "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",
                          "account_data": [
                            {
                              "type": "m.tag",
                              "content": {"tags": {"work": {"order": 1}}}
                            },
                            {
                              "type": "org.example.custom.room.config",
                              "content": {
                                "custom_config_key": "custom_config_value"
                              }
                            }
                          ]
                      }
                  ]
              }
          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": "../../event-schemas/schema/core-event-schema/event.json"
              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"]
                    invite:
                        type: object
                        title: "InviteEvent"
                        description: "The invite event if ``membership`` is ``invite``"
                        allOf:
                          - "$ref": "../../event-schemas/schema/m.room.member"
                    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: |-
                            If the user is a member of the room this will be a
                            list of the most recent messages for this room. If
                            the user has left the room this will be the
                            messages that preceeded them leaving. This array
                            will consist of at most ``limit`` elements.
                          items:
                            type: object
                            title: RoomEvent
                            allOf:
                              - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
                      required: ["start", "end", "chunk"]
                    state:
                      type: array
                      description: |-
                        If the user is a member of the room this will be the
                        current state of the room as a list of events. If the
                        user has left the room this will be the state of the
                        room when they left it.
                      items:
                        title: StateEvent
                        type: object
                        allOf:
                          - "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
                    visibility:
                      type: string
                      enum: ["private", "public"]
                      description: |-
                        Whether this room is visible to the ``/publicRooms`` API
                        or not."
                    account_data:
                      type: array
                      description: |-
                        The private data that this user has attached to
                        this room.
                      items:
                        title: Event
                        type: object
                        allOf:
                          - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
                  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": "../../event-schemas/schema/core-event-schema/event.json"
        404:
          description: The event was not found or you do not have permission to read this event.