matrix-spec-proposals/api/client-server/rooms.yaml

swagger: '2.0'
info:
  title: "Matrix Client-Server Rooms API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
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:
  "/rooms/{roomId}/state/{eventType}/{stateKey}":
    get:
      summary: Get the state identified by the type and key.
      description: |-
        Looks up the contents of a state event in a room. If the user is
        joined to the room then the state is taken from the current
        state of the room. If the user has left the room then the state is
        taken from the state of the room when they left.
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to look up the state in.
          required: true
          x-example: "!636q39766251:example.com"
        - in: path
          type: string
          name: eventType
          description: The type of state to look up.
          required: true
          x-example: "m.room.name"
        - in: path
          type: string
          name: stateKey
          description: The key of the state to look up.
          required: true
          x-example: ""
      responses:
        200:
          description: The content of the state event.
          examples:
            application/json: |-
              {"name": "Example room name"}
          schema:
            type: object
        404:
          description: The room has no state with the given type or key.
        403:
          description: >
            You aren't a member of the room and weren't previously a
            member of the room.
      tags:
        - Room participation
  "/rooms/{roomId}/state/{eventType}":
    get:
      summary: Get the state identified by the type, with the empty state key.
      description: |-
        Looks up the contents of a state event in a room. If the user is
        joined to the room then the state is taken from the current
        state of the room. If the user has left the room then the state is
        taken from the state of the room when they left.

        This looks up the state event with the empty state key.
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to look up the state in.
          required: true
          x-example: "!636q39766251:example.com"
        - in: path
          type: string
          name: eventType
          description: The type of state to look up.
          required: true
          x-example: "m.room.name"
      responses:
        200:
          description: The content of the state event.
          examples:
            application/json: |-
              {"name": "Example room name"}
          schema:
            type: object
        404:
          description: The room has no state with the given type or key.
        403:
          description: >
            You aren't a member of the room and weren't previously a
            member of the room.
      tags:
        - Room participation
  "/rooms/{roomId}/state":
    get:
      summary: Get all state events in the current state of a room.
      description: |-
        Get the state events for the current state of a room.
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to look up the state for.
          required: true
          x-example: "!636q39766251:example.com"
      responses:
        200:
          description: The current state of the room
          examples:
            application/json: |-
              [
                {
                    "age": 7148266897,
                    "content": {
                        "join_rule": "public"
                    },
                    "event_id": "$14259997323TLwtb:example.com",
                    "origin_server_ts": 1425999732392,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.join_rules",
                    "sender": "@alice:example.com"
                },
                {
                    "age": 6547561012,
                    "content": {
                        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
                        "membership": "join"
                    },
                    "event_id": "$1426600438280zExKY:example.com",
                    "membership": "join",
                    "origin_server_ts": 1426600438277,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@alice:example.com",
                    "type": "m.room.member",
                    "sender": "@alice:example.com"
                },
                {
                    "age": 7148267200,
                    "content": {
                        "creator": "@alice:example.com"
                    },
                    "event_id": "$14259997320KhbwJ:example.com",
                    "origin_server_ts": 1425999732089,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.create",
                    "sender": "@alice:example.com"
                },
                {
                    "age": 1622568720,
                    "content": {
                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                        "displayname": "Bob",
                        "membership": "join"
                    },
                    "event_id": "$1431525430134MxlLX:example.com",
                    "origin_server_ts": 1431525430569,
                    "replaces_state": "$142652023736BSXcM:example.com",
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@bob:example.com",
                    "type": "m.room.member",
                    "sender": "@bob:example.com"
                },
                {
                    "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:example.com": 100
                         },
                         "users_default": 0
                    },
                    "event_id": "$14259997322mqfaq:example.com",
                    "origin_server_ts": 1425999732285,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.power_levels",
                    "sender": "@alice:example.com"
                }
              ]
          schema:
            type: array
            title: RoomState
            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 then this will be the state of the room
              when they left as a list of events.
            items:
              title: StateEvent
              type: object
              allOf:
                - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
        403:
          description: >
            You aren't a member of the room and weren't previously a
            member of the room.
      tags:
        - Room participation
  "/rooms/{roomId}/initialSync":
    get:
      summary: Snapshot the current state of a room and its most recent messages.
      description: |-
        Get a copy of the current state and the most recent messages in a room.
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to get the data.
          required: true
          x-example: "!636q39766251:example.com"
      responses:
        200:
          description: The current state of the room
          examples:
            application/json: |-
              {
                "membership": "join",
                "messages": {
                  "chunk": [
                    {
                      "age": 343513403,
                      "content": {
                        "body": "foo",
                        "msgtype": "m.text"
                      },
                      "event_id": "$14328044851tzTJS:example.com",
                      "origin_server_ts": 1432804485886,
                      "room_id": "!636q39766251:example.com",
                      "type": "m.room.message",
                      "sender": "@alice:example.com"
                    },
                    {
                      "age": 343511809,
                      "content": {
                        "body": "bar",
                        "msgtype": "m.text"
                      },
                      "event_id": "$14328044872spjFg:example.com",
                      "origin_server_ts": 1432804487480,
                      "room_id": "!636q39766251:example.com",
                      "type": "m.room.message",
                      "sender": "@bob:example.com"
                    }
                  ],
                  "end": "s3456_9_0",
                  "start": "t44-3453_9_0"
                },
                "room_id": "!636q39766251:example.com",
                "state": [
                  {
                    "age": 7148266897,
                    "content": {
                      "join_rule": "public"
                    },
                    "event_id": "$14259997323TLwtb:example.com",
                    "origin_server_ts": 1425999732392,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.join_rules",
                    "sender": "@alice:example.com"
                  },
                  {
                    "age": 6547561012,
                    "content": {
                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
                      "membership": "join"
                    },
                    "event_id": "$1426600438280zExKY:example.com",
                    "membership": "join",
                    "origin_server_ts": 1426600438277,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@alice:example.com",
                    "type": "m.room.member",
                    "sender": "@alice:example.com"
                  },
                  {
                    "age": 7148267200,
                    "content": {
                        "creator": "@alice:example.com"
                    },
                    "event_id": "$14259997320KhbwJ:example.com",
                    "origin_server_ts": 1425999732089,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.create",
                    "sender": "@alice:example.com"
                  },
                  {
                    "age": 1622568720,
                    "content": {
                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                        "displayname": "Bob",
                        "membership": "join"
                    },
                    "event_id": "$1431525430134MxlLX:example.com",
                    "origin_server_ts": 1431525430569,
                    "replaces_state": "$142652023736BSXcM:example.com",
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@bob:example.com",
                    "type": "m.room.member",
                    "sender": "@bob:example.com"
                  },
                  {
                    "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:example.com": 100
                      },
                      "users_default": 0
                    },
                    "event_id": "$14259997322mqfaq:example.com",
                    "origin_server_ts": 1425999732285,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "",
                    "type": "m.room.power_levels",
                    "sender": "@alice:example.com"
                  }
                ],
                "visibility": "private",
                "account_data": [{
                    "type": "m.tag",
                    "content": {"tags": {"work": {"order": "1"}}}
                }]
              }
          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 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.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": "../../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": "../../event-schemas/schema/core-event-schema/event.yaml"
            required: ["room_id"]
        403:
          description: >
            You aren't a member of the room and weren't previously a
            member of the room.
      tags:
        - Room participation
  "/rooms/{roomId}/members":
    get:
      summary: Get the m.room.member events for the room.
      description:
        Get the list of members for this room.
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to get the member events for.
          required: true
          x-example: "!636q39766251:example.com"
      responses:
        200:
          description: |-
            A list of members of the room. If you are joined to the room then
            this will be the current members of the room. If you have left te
            room then this will be the members of the room when you left.
          examples:
            application/json: |-
              {
                "chunk": [
                  {
                    "age": 6547561012,
                    "content": {
                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
                      "membership": "join"
                    },
                    "event_id": "$1426600438280zExKY:example.com",
                    "membership": "join",
                    "origin_server_ts": 1426600438277,
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@alice:example.com",
                    "type": "m.room.member",
                    "sender": "@alice:example.com"
                  },
                  {
                    "age": 1622568720,
                    "content": {
                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                        "displayname": "Bob",
                        "membership": "join"
                    },
                    "event_id": "$1431525430134MxlLX:example.com",
                    "origin_server_ts": 1431525430569,
                    "replaces_state": "$142652023736BSXcM:example.com",
                    "room_id": "!636q39766251:example.com",
                    "state_key": "@bob:example.com",
                    "type": "m.room.member",
                    "sender": "@bob:example.com"
                  }
                ]
              }
          schema:
            type: object
            properties:
              chunk:
                type: array
                items:
                  title: MemberEvent
                  type: object
                  allOf:
                    - "$ref": "../../event-schemas/schema/m.room.member"
        403:
          description: >
            You aren't a member of the room and weren't previously a
            member of the room.
      tags:
        - Room participation