async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,138 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Summary API
+  version: 1.0.0
+paths:
+  "/room_summary/{roomIdOrAlias}":
+    get:
+      x-addedInMatrixVersion: "1.15"
+      summary: Retrieves a summary for a room.
+      description: |-
+        Retrieves a summary for a room.
+
+        Clients should note that requests for rooms where the user's membership
+        is `invite` or `knock` might yield outdated, partial or even no data
+        since the server may not have access to the current state of the room.
+
+        Servers MAY allow unauthenticated access to this API if at least one of
+        the following conditions holds true:
+
+        - The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
+          `knock_restricted`.
+        - The room has a `world_readable` [history visibility](#room-history-visibility).
+
+        Servers should consider rate limiting requests that require a federation
+        request more heavily if the client is unauthenticated.
+      operationId: getRoomSummary
+      security:
+        - signedRequest: []
+      parameters:
+        - in: path
+          name: roomIdOrAlias
+          description: The room identifier or alias to summarise.
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            oneOf:
+              - type: string
+                format: mx-room-id
+                pattern: "^!"
+              - type: string
+                format: mx-room-alias
+                pattern: "^#"
+        - in: query
+          name: via
+          description: |-
+            The servers to attempt to request the summary from when
+            the local server cannot generate it (for instance, because
+            it has no local user in the room).
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+              format: mx-server-name
+      responses:
+        "200":
+          description: A summary of the room.
+          content:
+            application/json:
+              schema:
+                description: A summary of the room.
+                allOf:
+                  - $ref: ../client-server/definitions/room_summary.yaml
+                  - type: object
+                    properties:
+                      membership:
+                        description: |-
+                          The membership state of the user if the user is joined to the room. Absent
+                          if the API was called unauthenticated.
+                        enum:
+                          - invite
+                          - join
+                          - knock
+                          - leave
+                          - ban
+                        type: string
+              examples:
+                response:
+                  value: {
+                    room_id: "!ol19s:bleecker.street",
+                    avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
+                    guest_can_join: false,
+                    name: "CHEESE",
+                    num_joined_members: 37,
+                    topic: "Tasty tasty cheese",
+                    world_readable: true,
+                    join_rule: "public",
+                    room_type: "m.space",
+                    membership: "invite",
+                    encryption: "m.megolm.v1.aes-sha2",
+                    room_version: "9001",
+                  }
+        "404":
+          description: |-
+            The room could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found."
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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

@@ -0,0 +1,130 @@
+# Copyright 2019 New Vector 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Upgrades API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/upgrade":
+    post:
+      summary: Upgrades a room to a new room version.
+      description: Upgrades the given room to a particular room version.
+      operationId: upgradeRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to upgrade.
+          example: "!oldroom:example.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                new_version:
+                  type: string
+                  description: The new version for the room.
+                additional_creators:
+                  type: array
+                  items:
+                    type: string
+                    description: Additional user ID to consider a room creator, if the room version supports it.
+                  x-addedInMatrixVersion: "1.16"
+                  description: |-
+                    When upgrading to a [room version](/rooms) which supports additional creators,
+                    the [user IDs](/appendices#user-identifiers) which should be considered room
+                    creators in addition to the user performing the upgrade.
+
+                    If the room being upgraded has additional creators, they are *not* automatically
+                    copied to the new room. The full set of additional creators needs to be set to
+                    retain (or add/remove) more room creators.
+
+                    When upgrading to a room version which doesn't support additional creators, this
+                    field is ignored and has no effect during the upgrade process.
+              example: {
+                "new_version": "2"
+              }
+              required:
+                - new_version
+        required: true
+      responses:
+        "200":
+          description: The room was successfully upgraded.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  replacement_room:
+                    type: string
+                    description: The ID of the new room.
+                required:
+                  - replacement_room
+              examples:
+                response:
+                  value: {
+                    "replacement_room": "!newroom:example.org"
+                  }
+        "400":
+          description: |-
+            The request was invalid. One way this can happen is if the room version
+            requested is not supported by the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNSUPPORTED_ROOM_VERSION",
+                    "error": "This server does not support that room version"
+                  }
+        "403":
+          description: The user is not permitted to upgrade the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You cannot upgrade this room"
+                  }
+      tags:
+        - Room upgrades
+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

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

@@ -0,0 +1,380 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Rooms API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/event/{eventId}":
+    get:
+      summary: Get a single event by event ID.
+      description: |-
+        Get a single event based on `roomId/eventId`. You must have permission to
+        retrieve this event e.g. by being a member in the room for this event.
+      operationId: getOneRoomEvent
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The ID of the room the event is in.
+          required: true
+          example: "!636q39766251:matrix.org"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: path
+          name: eventId
+          description: The event ID to get.
+          required: true
+          example: $asfDuShaf7Gafaw:matrix.org
+          schema:
+            type: string
+            format: mx-event-id
+            pattern: "^\\$"
+      responses:
+        "200":
+          description: The full event.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/client_event.yaml
+              examples:
+                response:
+                  value: {
+                    "room_id": "!636q39766251:matrix.org",
+                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                  }
+        "404":
+          description: The event was not found or you do not have permission to read this
+            event.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Event not found."
+                  }
+      tags:
+        - Room participation
+  "/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.
+      operationId: getRoomStateWithKey
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to look up the state in.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: path
+          name: eventType
+          description: The type of state to look up.
+          required: true
+          example: m.room.name
+          schema:
+            type: string
+        - in: path
+          name: stateKey
+          description: |-
+            The key of the state to look up. Defaults to an empty string. When
+            an empty string, the trailing slash on this endpoint is optional.
+          required: true
+          example: ""
+          schema:
+            type: string
+        - in: query
+          name: format
+          x-addedInMatrixVersion: "1.16"
+          description: |-
+            The format to use for the returned data. `content` (the default) will
+            return only the content of the state event. `event` will return the entire
+            event in the usual format suitable for clients, including fields like event
+            ID, sender and timestamp.
+          example: event
+          schema:
+            type: string
+            enum:
+            - content
+            - event
+      responses:
+        "200":
+          description: |-
+            The content of the state event, or the entire client-formatted event
+            if `?format=event` was used.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                  - $ref: "../../event-schemas/schema/core-event-schema/state_event.yaml"
+              examples:
+                response:
+                  value: {
+                    "name": "Example room name"
+                  }
+        "403":
+          description: |
+            You aren't a member of the room and weren't previously a member of the room.
+        "404":
+          description: The room has no state with the given type or key.
+      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.
+      operationId: getRoomState
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to look up the state for.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+      responses:
+        "200":
+          description: The current state of the room
+          content:
+            application/json:
+              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:
+                  $ref: definitions/client_event.yaml
+              examples:
+                response:
+                  value: [
+                    {
+                      "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"
+                    }
+                  ]
+        "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.
+      operationId: getMembersByRoom
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to get the member events for.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: query
+          name: at
+          description: |-
+            The point in time (pagination token) to return members for in the room.
+            This token can be obtained from a `prev_batch` token returned for
+            each room by the sync API. Defaults to the current state of the room,
+            as determined by the server.
+          example: YWxsCgpOb25lLDM1ODcwOA
+          schema:
+            type: string
+        # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
+        # filter might be a better alternative.
+        # See https://github.com/matrix-org/matrix-doc/issues/1227
+        - in: query
+          name: membership
+          description: |-
+            The kind of membership to filter for. Defaults to no filtering if
+            unspecified. When specified alongside `not_membership`, the two
+            parameters create an 'or' condition: either the membership *is*
+            the same as `membership` **or** *is not* the same as `not_membership`.
+          example: join
+          schema:
+            type: string
+            enum:
+              - join
+              - invite
+              - knock
+              - leave
+              - ban
+        - in: query
+          name: not_membership
+          description: |-
+            The kind of membership to exclude from the results. Defaults to no
+            filtering if unspecified.
+          example: leave
+          schema:
+            type: string
+            enum:
+              - join
+              - invite
+              - knock
+              - leave
+              - ban
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      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.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  chunk:
+                    type: array
+                    items:
+                      $ref: definitions/client_event.yaml
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.member.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}/joined_members":
+    get:
+      summary: Gets the list of currently joined users and their profile data.
+      description: This API returns a map of MXIDs to member info objects for members
+        of the room. The current user must be in the room for it to work, unless
+        it is an Application Service in which case any of the AS's users must be
+        in the room. This API is primarily for Application Services and should
+        be faster to respond than `/members` as it can be implemented more
+        efficiently on the server.
+      operationId: getJoinedMembersByRoom
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to get the members of.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: A map of MXID to room member objects.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  joined:
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        title: RoomMember
+                        type: object
+                        properties:
+                          display_name:
+                            type: string
+                            description: The display name of the user this object is representing.
+                          avatar_url:
+                            type: string
+                            format: uri
+                            description: The avatar of the user this object is representing, as an [`mxc://`
+                              URI](/client-server-api/#matrix-content-mxc-uris).
+                    description: A map from user ID to a RoomMember object.
+                    type: object
+              examples:
+                response:
+                  value: {
+                    "joined": {
+                      "@bar:example.com": {
+                        "display_name": "Bar",
+                        "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
+                      }
+                    }
+                  }
+        "403":
+          description: |
+            You aren't a member of the room.
+      tags:
+        - Room participation
+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