# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# See the License for the specific language governing permissions and
# limitations under the License.
# limitations under the License.
swagger:'2.0'
openapi:3.1.0
info:
info:
title:"Matrix Client-Server Application Service Ping API"
title:Matrix Client-Server Application Service Ping API
version:"1.0.0"
version:1.0.0
host:localhost:8008
schemes:
- https
- http
basePath:/_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref:definitions/security.yaml
paths:
paths:
"/appservice/{appserviceId}/ping":
"/appservice/{appserviceId}/ping":
post:
post:
x-addedInMatrixVersion:"1.7"
x-addedInMatrixVersion:"1.7"
summary:|-
summary:Ask the homeserver to ping the application service to ensure the
Ask the homeserver to ping the application service to ensure the connection works.
connection works.
description:|-
description:|-
This API asks the homeserver to call the
This API asks the homeserver to call the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
@ -48,63 +35,79 @@ paths:
operationId:pingAppservice
operationId:pingAppservice
parameters:
parameters:
- in:path
- in:path
type:string
name:appserviceId
name:appserviceId
description:|-
description:|-
The appservice ID of the appservice to ping. This must be the same
The appservice ID of the appservice to ping. This must be the same
as the appservice whose `as_token` is being used to authenticate the
as the appservice whose `as_token` is being used to authenticate the
request.
request.
required:true
required:true
x-example:"telegram"
example:telegram
- in:body
name:body
required:true
schema:
schema:
type:object
type:string
properties:
requestBody:
transaction_id:
content:
type:string
application/json:
description:|-
schema:
An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.
type:object
example:"mautrix-go_1683636478256400935_123"
properties:
transaction_id:
type:string
description:An optional transaction ID that is passed through to the
`/_matrix/app/v1/ping` call.
example:mautrix-go_1683636478256400935_123
required:true
security:
security:
# again, this is the appservice's token - not a typical client's
# again, this is the appservice's token - not a typical client's
- accessToken:[]
- accessToken:[]
responses:
responses:
200:
"200":
description:The ping was successful.
description:The ping was successful.
schema:
content:
type:object
application/json:
properties:
schema:
duration_ms:
type:object
type:integer
properties:
description:|-
duration_ms:
The duration in milliseconds that the
type:integer
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
description:|-
request took from the homeserver's point of view.
The duration in milliseconds that the
required:
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
- duration_ms
request took from the homeserver's point of view.
examples:
required:
application/json:{"duration_ms": 123}
- duration_ms
400:
examples:
description:The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`.
response:
schema:
value:{
$ref:"definitions/errors/error.yaml"
"duration_ms": 123
examples:
}
application/json:{
"400":
"errcode": "M_URL_NOT_SET",
description:The application service doesn't have a URL configured. The errcode
"error": "Application service doesn't have a URL configured"
is `M_URL_NOT_SET`.
}
content:
403:
application/json:
description:The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`.
schema:
schema:
$ref:definitions/errors/error.yaml
$ref:"definitions/errors/error.yaml"
examples:
examples:
response:
application/json:{
value:{
"errcode": "M_FORBIDDEN",
"errcode": "M_URL_NOT_SET",
"error": "Provided access token is not the appservice's as_token"
"error": "Application service doesn't have a URL configured"
}
}
502:
"403":
description:The access token used to authenticate the request doesn't belong to
an appservice, or belongs to a different appservice than the one in
the path. The errcode is `M_FORBIDDEN`.
content:
application/json:
schema:
$ref:definitions/errors/error.yaml
examples:
response:
value:{
"errcode": "M_FORBIDDEN",
"error": "Provided access token is not the appservice's as_token"
}
"502":
description:|-
description:|-
The application service returned a bad status, or the connection failed.
The application service returned a bad status, or the connection failed.
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
@ -112,41 +115,68 @@ paths:
For bad statuses, the response may include `status` and `body`
For bad statuses, the response may include `status` and `body`
fields containing the HTTP status code and response body text
fields containing the HTTP status code and response body text
respectively to aid with debugging.
respectively to aid with debugging.
schema:
content:
type:object
application/json:
title:Error
schema:
description:A Matrix-level Error
type:object
properties:
title:Error
errcode:
description:A Matrix-level Error
type:string
properties:
description:An error code.
errcode:
enum:[M_BAD_STATUS, M_CONNECTION_FAILED]
type:string
error:
description:An error code.
type:string
enum:
description:A human-readable error message.
- M_BAD_STATUS
example:Ping returned status 401
- M_CONNECTION_FAILED
status:
error:
type:integer
type:string
description:The HTTP status code returned by the appservice.
description:A human-readable error message.
example:401
example:Ping returned status 401
body:
status:
type:string
type:integer
description:The HTTP response body returned by the appservice.
description:The HTTP status code returned by the appservice.
example:"{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
example:401
required:["errcode"]
body:
examples:
type:string
application/json:{
description:The HTTP response body returned by the appservice.
"errcode": "M_BAD_STATUS",
example:'{"errcode": "M_UNKNOWN_TOKEN"}'
"error": "Ping returned status 401",
required:
"status": 401,
- errcode
"body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
examples:
}
response:
504:
value:{
description:The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`.
"errcode": "M_BAD_STATUS",
schema:
"error": "Ping returned status 401",
$ref:"definitions/errors/error.yaml"
"status": 401,
examples:
"body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
application/json:{
}
"errcode": "M_CONNECTION_TIMEOUT",
"504":
"error": "Connection to application service timed out"
description:The connection to the application service timed out. The errcode is
}
`M_CONNECTION_TIMEOUT`.
content:
application/json:
schema:
$ref:definitions/errors/error.yaml
examples:
response:
value:{
"errcode": "M_CONNECTION_TIMEOUT",
"error": "Connection to application service timed out"
}
servers:
- url:"{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default:https
hostname:
default:localhost:8008
basePath:
default:/_matrix/client/v1
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
description:The user has been kicked and banned from the room.
description:The user has been kicked and banned from the room.
examples:
content:
application/json:{
application/json:
}
schema:
schema:
type:object
type:object
examples:
403:
response:
value:{}
"403":
description:|-
description:|-
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room.
- The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room.
- The banner's power level is insufficient to ban users from the room.
examples:
content:
application/json:{
application/json:
"errcode": "M_FORBIDDEN",
schema:
"error": "You do not have a high enough power level to ban from this room."
$ref:definitions/errors/error.yaml
}
examples:
schema:
response:
"$ref": "definitions/errors/error.yaml"
value:{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags:
tags:
- Room membership
- Room membership
"/rooms/{roomId}/unban":
"/rooms/{roomId}/unban":
@ -101,50 +99,74 @@ paths:
- accessToken:[]
- accessToken:[]
parameters:
parameters:
- in:path
- in:path
type:string
name:roomId
name:roomId
description:The room identifier (not alias) from which the user should be unbanned.
description:The room identifier (not alias) from which the user should be
required:true
unbanned.
x-example:"!e42d8c:matrix.org"
- in:body
name:body
required:true
required:true
example:"!e42d8c:matrix.org"
schema:
schema:
type:object
type:string
example:{
requestBody:
"user_id": "@cheeky_monkey:matrix.org",
content:
"reason": "They've been banned long enough"
application/json:
}
schema:
properties:
type:object
user_id:
example:{
type:string
"user_id": "@cheeky_monkey:matrix.org",
description:The fully qualified user ID of the user being unbanned.
"reason": "They've been banned long enough"
reason:
}
x-addedInMatrixVersion:"1.1"
properties:
type:string
user_id:
description:|-
type:string
Optional reason to be included as the `reason` on the subsequent
description:The fully qualified user ID of the user being unbanned.
membership event.
reason:
required:["user_id"]
x-addedInMatrixVersion:"1.1"
type:string
description:|-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required:true
responses:
responses:
200:
"200":
description:The user has been unbanned from the room.
description:The user has been unbanned from the room.
examples:
content:
application/json:{
application/json:
}
schema:
schema:
type:object
type:object
examples:
403:
response:
value:{}
"403":
description:|-
description:|-
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room.
- The unbanner's power level is insufficient to unban users from the room.
examples:
content:
application/json:{
application/json:
"errcode": "M_FORBIDDEN",
schema:
"error": "You do not have a high enough power level to unban from this room."
$ref:definitions/errors/error.yaml
}
examples:
schema:
response:
"$ref": "definitions/errors/error.yaml"
value:{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# See the License for the specific language governing permissions and
# limitations under the License.
# limitations under the License.
swagger:'2.0'
openapi:3.1.0
info:
info:
title:"Matrix Client-Server Room Joining API"
title:Matrix Client-Server Room Joining API
version:"1.0.0"
version:1.0.0
host:localhost:8008
schemes:
- https
- http
basePath:/_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref:definitions/security.yaml
paths:
paths:
# With an extra " " to disambiguate from the 3pid invite endpoint
# 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.
# The extra space makes it sort first for what I'm sure is a good reason.
@ -47,48 +36,53 @@ paths:
If the user was invited to the room, the homeserver will append a
If the user was invited to the room, the homeserver will append a
`m.room.member` event to the room.
`m.room.member` event to the room.
operationId:inviteUser
operationId:inviteUser
security:
security:
- accessToken:[]
- accessToken:[]
parameters:
parameters:
- in:path
- in:path
type:string
name:roomId
name:roomId
description:The room identifier (not alias) to which to invite the user.
description:The room identifier (not alias) to which to invite the user.
required:true
required:true
x-example:"!d41d8cd:matrix.org"
example:"!d41d8cd:matrix.org"
- in:body
name:body
required:true
schema:
schema:
type:object
type:string
example:{
requestBody:
"user_id": "@cheeky_monkey:matrix.org",
content:
"reason": "Welcome to the team!"
application/json:
}
schema:
properties:
type:object
user_id:
example:{
type:string
"user_id": "@cheeky_monkey:matrix.org",
description:The fully qualified user ID of the invitee.
"reason": "Welcome to the team!"
reason:
x-addedInMatrixVersion:"1.1"
type:string
description:|-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:["user_id"]
responses:
200:
description:The user has been invited to join the room, or was already invited to the room.
examples:
application/json:{
}
}
schema:
properties:
type:object
user_id:
400:
type:string
description:The fully qualified user ID of the invitee.
reason:
x-addedInMatrixVersion:"1.1"
type:string
description:|-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required:true
responses:
"200":
description:The user has been invited to join the room, or was already invited
to the room.
content:
application/json:
schema:
type:object
examples:
response:
value:{}
"400":
description:|-
description:|-
The request is invalid. A meaningful `errcode` and description
The request is invalid. A meaningful `errcode` and description
error text will be returned. Example reasons for rejection include:
error text will be returned. Example reasons for rejection include:
@ -98,9 +92,11 @@ paths:
- One or more users being invited to the room are residents of a
- One or more users being invited to the room are residents of a
homeserver which does not support the requested room version. The
homeserver which does not support the requested room version. The
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
schema:
content:
"$ref": "definitions/errors/error.yaml"
application/json:
403:
schema:
$ref:definitions/errors/error.yaml
"403":
description:|-
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:
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:
@ -108,14 +104,36 @@ paths:
- The invitee is already a member of the room.
- The invitee is already a member of the room.
- The inviter is not currently in the room.
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
- The inviter's power level is insufficient to invite users to the room.
examples:
content:
application/json:{
application/json:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
schema:
$ref:definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml"
examples:
429:
response:
value:{
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
You aren't a member of the room and weren't previously a member of the room.
type:object
properties:
chunk:
type:array
items:
$ref:"definitions/client_event.yaml"
403:
description:>
You aren't a member of the room and weren't previously a
member of the room.
tags:
tags:
- Room participation
- Room participation
"/rooms/{roomId}/joined_members":
"/rooms/{roomId}/joined_members":
get:
get:
summary:Gets the list of currently joined users and their profile data.
summary:Gets the list of currently joined users and their profile data.
description:
description:This API returns a map of MXIDs to member info objects for members
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.
of the room. The current user must be in the room for it to work, unless
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.
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
description:The user has been invited to join the room.
description:The user has been invited to join the room.
examples:
content:
application/json:{
application/json:
}
schema:
schema:
type:object
type:object
examples:
403:
response:
value:{}
"403":
description:|-
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:
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:
@ -128,14 +125,36 @@ paths:
- The invitee is already a member of the room.
- The invitee is already a member of the room.
- The inviter is not currently in the room.
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
- The inviter's power level is insufficient to invite users to the room.
examples:
content:
application/json:{
application/json:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
schema:
$ref:definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml"
examples:
429:
response:
value:{
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
"error": "Unknown or invalid pepper - has it been rotated?"
The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops.
}
`M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server.