matrix-spec-proposals/api/client-server/rooms.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 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:
  $ref: definitions/security.yaml
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": "definitions/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}/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 the
            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": "definitions/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