You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/api/client-server/room_state.yaml

133 lines
4.7 KiB
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