matrix-spec/api/client-server/room_state.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 state event send 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}":
    put:
      summary: Send a state event to the given room.
      description: |
        .. For backwards compatibility with older links...
        .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:

        State events can be sent using this endpoint.  These events will be
        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
        match.

        Requests to this endpoint **cannot use transaction IDs**
        like other ``PUT`` paths because they cannot be differentiated from the
        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.

        The body of the request should be the content object of the event; the
        fields in this object will vary depending on the type of event. See
        `Room Events`_ for the ``m.`` event specification.

        If the event type being sent is ``m.room.canonical_alias`` servers
        SHOULD ensure that any new aliases being listed in the event are valid
        per their grammar/syntax and that they point to the room ID where the
        state event is to be sent. Servers do not validate aliases which are
        being removed or are already present in the state event.        
      operationId: setRoomStateWithKey
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to set the state in
          required: true
          x-example: "!636q39766251:example.com"
        - in: path
          type: string
          name: eventType
          description: The type of event to send.
          required: true
          x-example: "m.room.member"
        - in: path
          type: string
          name: stateKey
          description: |-
            The state_key for the state to send. Defaults to the empty string. When
            an empty string, the trailing slash on this endpoint is optional.            
          required: true
          x-example: "@alice:example.com"
        - in: body
          name: body
          schema:
            type: object
            example: {
                "membership": "join",
                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
                "displayname": "Alice Margatroid"
              }
      responses:
        200:
          description: "An ID for the sent event."
          examples:
            application/json: {
                  "event_id": "$YUwRidLecu:example.com"
              }
          schema:
            type: object
            properties:
              event_id:
                type: string
                description: |-
                                    A unique identifier for the event.
            required:
              - event_id
        403:
          description: |-
                        The sender doesn't have permission to send the event into the room.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_FORBIDDEN",
              "error": "You do not have permission to send the event."
            }
        400:
          description: |-
            The sender's request is malformed.

            Some example error codes include:

            * ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``
              event have invalid syntax.

            * ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event
              do not point to the room ID for which the state event is to be sent to.            
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_BAD_ALIAS",
              "error": "The alias '#hello:example.org' does not point to this room."
            }
      tags:
        - Room participation