2016-07-12 16:22:33 +00:00
# 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.
2015-09-08 15:35:08 +00:00
swagger : '2.0'
info :
2015-12-04 11:09:35 +00:00
title : "Matrix Client-Server Room Joining API"
2015-09-08 15:35:08 +00:00
version : "1.0.0"
host : localhost:8008
schemes :
- https
- http
2015-12-04 11:09:35 +00:00
basePath : /_matrix/client/%CLIENT_MAJOR_VERSION%
2015-09-08 15:35:08 +00:00
consumes :
- application/json
produces :
- application/json
securityDefinitions :
2016-05-03 12:57:16 +00:00
$ref : definitions/security.yaml
2015-09-08 15:35:08 +00:00
paths :
2015-09-10 15:46:22 +00:00
# With an extra " " to disambiguate from the 3pid invite endpoint
# The extra space makes it sort first for what I'm sure is a good reason.
"/rooms/{roomId}/invite " :
2015-09-09 16:55:40 +00:00
post :
summary : Invite a user to participate in a particular room.
description : |-
2015-11-05 18:11:20 +00:00
.. _invite-by-user-id-endpoint :
2015-09-10 15:46:22 +00:00
*Note that there are two forms of this API, which are documented separately.
This version of the API requires that the inviter knows the Matrix
2015-11-05 18:11:20 +00:00
identifier of the invitee. The other is documented in the*
`third party invites section`_.
2015-09-10 15:46:22 +00:00
2015-09-09 16:55:40 +00:00
This API invites a user to participate in a particular room.
They do not start participating in the room until they actually join the
room.
Only users currently in a particular room can invite other users to
join that room.
2015-09-10 15:46:22 +00:00
2015-12-02 19:23:33 +00:00
If the user was invited to the room, the homeserver will append a
2015-09-10 15:46:22 +00:00
``m.room.member`` event to the room.
2015-11-05 18:11:20 +00:00
.. _third party invites section : `invite-by-third-party-id-endpoint`_
2017-08-02 23:19:34 +00:00
operationId : inviteUser
2015-09-09 16:55:40 +00:00
security :
- accessToken : [ ]
parameters :
- in : path
type : string
name : roomId
2015-09-10 10:21:18 +00:00
description : The room identifier (not alias) to which to invite the user.
2015-09-09 16:55:40 +00:00
required : true
2015-09-10 10:21:18 +00:00
x-example : "!d41d8cd:matrix.org"
2015-09-09 16:55:40 +00:00
- in : body
2015-09-10 15:46:22 +00:00
name : body
2015-09-09 16:55:40 +00:00
required : true
schema :
type : object
2017-09-26 16:53:28 +00:00
example : {
2015-09-09 16:55:40 +00:00
"user_id": "@cheeky_monkey:matrix.org"
}
properties :
user_id :
type : string
description : The fully qualified user ID of the invitee.
required : [ "user_id" ]
responses :
200 :
description : The user has been invited to join the room.
examples :
2017-09-26 16:53:28 +00:00
application/json : {
}
2015-09-09 16:55:40 +00:00
schema :
2015-09-10 15:46:22 +00:00
type : object
403 :
description : |-
You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are :
2015-10-23 10:36:07 +00:00
2015-10-23 09:51:31 +00:00
- The invitee has been banned from the room.
- The invitee is already a member of the room.
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
2015-09-10 15:46:22 +00:00
examples :
2017-09-26 16:53:28 +00:00
application/json : {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room" }
2015-09-10 15:46:22 +00:00
429 :
description : This request was rate-limited.
schema :
"$ref": "definitions/error.yaml"
2015-12-07 12:45:13 +00:00
tags :
- Room membership