matrix-spec/data/api/client-server/room_initial_sync.yaml

openapi: 3.1.0
info:
  title: Matrix Client-Server Rooms API
  version: 1.0.0
paths:
  "/rooms/{roomId}/initialSync":
    get:
      summary: Snapshot the current state of a room and its most recent messages.
      description: |-
        {{% boxes/note %}}
        This api should now exclusively be used for "peeking" into publicly viewable rooms you're not a member of ([Room Previews](/client-server-api/#room-previews))
        {{% /boxes/note %}}
        Get a copy of the current state and the most recent messages in a room.

        Using this endpoint for something other than peeking was deprecated in r0 of this specification. \
        The relevant information for syncing is now returned by the
        [`/sync`](/client-server-api/#get_matrixclientv3sync) API. See the
        [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
      operationId: roomInitialSync
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: roomId
          description: The room to get the data.
          required: true
          example: "!636q39766251:example.com"
          schema:
            type: string
      responses:
        "200":
          description: The current state of the room
          content:
            application/json:
              schema:
                title: RoomInfo
                type: object
                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 start of `chunk`. Can be passed to
                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                          to retrieve earlier events.

                          If no earlier events are available, this property may be omitted from
                          the response.
                      end:
                        type: string
                        description: |-
                          A token which correlates to the end of `chunk`. Can be passed to
                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                          to retrieve later events.
                      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 preceded them leaving. This array
                          will consist of at most `limit` elements.
                        items:
                          $ref: definitions/client_event.yaml
                    required:
                      - 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:
                      $ref: definitions/client_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: ../../event-schemas/schema/core-event-schema/event.yaml
                required:
                  - room_id
              examples:
                response:
                  value: {
                    "membership": "join",
                    "messages": {
                      "chunk": [
                        {
                          "room_id": "!636q39766251:example.com",
                          "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                        },
                        {
                          "room_id": "!636q39766251:example.com",
                          "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
                        }
                      ],
                      "end": "s3456_9_0",
                      "start": "t44-3453_9_0"
                    },
                    "room_id": "!636q39766251:example.com",
                    "state": [
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
                      },
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.member.yaml"
                      },
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.create.yaml"
                      },
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
                      }
                    ],
                    "visibility": "private",
                    "account_data": [
                      {
                        "type": "m.tag",
                        "content": {
                          "tags": {
                            "work": {
                              "order": "1"
                            }
                          }
                        }
                      }
                    ]
                  }
        "403":
          description: |
            You aren't a member of the room and weren't previously a member of the room.
      tags:
        - Room participation
      deprecated: false
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer