matrix-spec-proposals/api/client-server/old_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
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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.

        This endpoint was deprecated in r0 of this specification. Clients
        should instead call the |/sync|_ API with a ``since`` parameter. See
        the `migration guide
        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
      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",
                    "sender": "@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": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
        400:
          description: "Bad pagination ``from`` parameter."
      tags:
        - Room participation
      deprecated: true
  "/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.

        This endpoint was deprecated in r0 of this specification. Clients
        should instead call the |/sync|_ API with no ``since`` parameter. See
        the `migration guide
        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
      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",
                                      "sender": "@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",
                                      "sender": "@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",
                                  "sender": "@alice:localhost"
                              },
                              {
                                  "age": 6547561012,
                                  "content": {
                                      "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
                                      "membership": "join"
                                  },
                                  "event_id": "$1426600438280zExKY:localhost",
                                  "membership": "join",
                                  "origin_server_ts": 1426600438277,
                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                  "state_key": "@alice:localhost",
                                  "type": "m.room.member",
                                  "sender": "@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",
                                  "sender": "@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",
                                  "sender": "@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",
                                  "sender": "@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": "definitions/event-schemas/schema/core-event-schema/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"]
                    invite:
                        type: object
                        title: "InviteEvent"
                        description: "The invite event if ``membership`` is ``invite``"
                        allOf:
                          - "$ref": "definitions/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": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
                      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": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
                    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": "definitions/event-schemas/schema/core-event-schema/event.yaml"
                  required: ["room_id", "membership"]
              account_data:
                type: array
                description: |-
                  The global private data created by this user.
                items:
                  title: Event
                  type: object
                  allOf:
                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
            required: ["end", "rooms", "presence"]
        404:
          description: There is no avatar URL for this user or this user does not exist.
      tags:
        - Room participation
      deprecated: true
  "/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.

        This endpoint was deprecated in r0 of this specification. Clients
        should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
      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",
                "sender": "@bob:matrix.org",
                "event_id": "$asfDuShaf7Gafaw:matrix.org",
                "type": "m.room.message"
              }
          schema:
            allOf:
              - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
        404:
          description: The event was not found or you do not have permission to read this event.
      tags:
        - Room participation
      deprecated: true