wbamberg
3 years ago
committed by
GitHub
commit
6914402338
@ -0,0 +1,32 @@
|
||||
# Copyright 2018 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.
|
||||
properties:
|
||||
alias:
|
||||
description: An alias for a matrix room.
|
||||
type: string
|
||||
example: "#freenode_#matrix:matrix.org"
|
||||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
type: string
|
||||
example: "irc"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
type: object
|
||||
example: {
|
||||
"network": "freenode",
|
||||
"channel": "#matrix"
|
||||
}
|
||||
required: ['alias', 'protocol', 'fields']
|
||||
title: Location
|
||||
type: object
|
||||
@ -0,0 +1,17 @@
|
||||
# Copyright 2018 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.
|
||||
type: array
|
||||
description: List of matched third party locations.
|
||||
items:
|
||||
$ref: location.yaml
|
||||
@ -0,0 +1,113 @@
|
||||
# Copyright 2018 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.
|
||||
title: Protocol
|
||||
type: object
|
||||
properties:
|
||||
user_fields:
|
||||
description: |-
|
||||
Fields which may be used to identify a third party user. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the nickname of a user.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party user.
|
||||
example: ["network", "nickname"]
|
||||
location_fields:
|
||||
description: |-
|
||||
Fields which may be used to identify a third party location. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the name of a channel.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party location.
|
||||
example: ["network", "channel"]
|
||||
icon:
|
||||
description: A content URI representing an icon for the third party protocol.
|
||||
type: string
|
||||
example: "mxc://example.org/aBcDeFgH"
|
||||
field_types:
|
||||
title: Field Types
|
||||
description: |-
|
||||
The type definitions for the fields defined in the `user_fields` and
|
||||
`location_fields`. Each entry in those arrays MUST have an entry here. The
|
||||
`string` key for this object is field name itself.
|
||||
|
||||
May be an empty object if no fields are defined.
|
||||
type: object
|
||||
additionalProperties:
|
||||
title: Field Type
|
||||
description: Definition of valid values for a field.
|
||||
type: object
|
||||
properties:
|
||||
regexp:
|
||||
description: |-
|
||||
A regular expression for validation of a field's value. This may be relatively
|
||||
coarse to verify the value as the application service providing this protocol
|
||||
may apply additional validation or filtering.
|
||||
type: string
|
||||
placeholder:
|
||||
description: An placeholder serving as a valid example of the field value.
|
||||
type: string
|
||||
required: ['regexp', 'placeholder']
|
||||
required: ['fieldname']
|
||||
example: {
|
||||
"network": {
|
||||
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
|
||||
"placeholder": "irc.example.org"
|
||||
},
|
||||
"nickname": {
|
||||
"regexp": "[^\\s#]+",
|
||||
"placeholder": "username"
|
||||
},
|
||||
"channel": {
|
||||
"regexp": "#[^\\s]+",
|
||||
"placeholder": "#foobar"
|
||||
}
|
||||
}
|
||||
instances:
|
||||
description: |-
|
||||
A list of objects representing independent instances of configuration.
|
||||
For example, multiple networks on IRC if multiple are provided by the
|
||||
same application service.
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
title: Protocol Instance
|
||||
properties:
|
||||
desc:
|
||||
type: string
|
||||
description: A human-readable description for the protocol, such as the name.
|
||||
example: "Freenode"
|
||||
icon:
|
||||
type: string
|
||||
description: |-
|
||||
An optional content URI representing the protocol. Overrides the one provided
|
||||
at the higher level Protocol object.
|
||||
example: "mxc://example.org/JkLmNoPq"
|
||||
fields:
|
||||
type: object
|
||||
description: Preset values for `fields` the client may use to search by.
|
||||
example: {
|
||||
"network": "freenode"
|
||||
}
|
||||
network_id:
|
||||
type: string
|
||||
description: A unique identifier across all instances.
|
||||
example: "freenode"
|
||||
required: ['desc', 'fields', 'network_id']
|
||||
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
|
||||
@ -0,0 +1,70 @@
|
||||
# Copyright 2018 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.
|
||||
type: object
|
||||
description: Dictionary of supported third party protocols.
|
||||
additionalProperties:
|
||||
$ref: protocol.yaml
|
||||
example: {
|
||||
"irc": {
|
||||
"user_fields": ["network", "nickname"],
|
||||
"location_fields": ["network", "channel"],
|
||||
"icon": "mxc://example.org/aBcDeFgH",
|
||||
"field_types": {
|
||||
"network": {
|
||||
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
|
||||
"placeholder": "irc.example.org"
|
||||
},
|
||||
"nickname": {
|
||||
"regexp": "[^\\s]+",
|
||||
"placeholder": "username"
|
||||
},
|
||||
"channel": {
|
||||
"regexp": "#[^\\s]+",
|
||||
"placeholder": "#foobar"
|
||||
}
|
||||
},
|
||||
"instances": [
|
||||
{
|
||||
"network_id": "freenode",
|
||||
"desc": "Freenode",
|
||||
"icon": "mxc://example.org/JkLmNoPq",
|
||||
"fields": {
|
||||
"network": "freenode.net",
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"gitter": {
|
||||
"user_fields": ["username"],
|
||||
"location_fields": ["room"],
|
||||
"field_types": {
|
||||
"username": {
|
||||
"regexp": "@[^\\s]+",
|
||||
"placeholder": "@username"
|
||||
},
|
||||
"room": {
|
||||
"regexp": "[^\\s]+\\/[^\\s]+",
|
||||
"placeholder": "matrix-org/matrix-doc"
|
||||
}
|
||||
},
|
||||
"instances": [
|
||||
{
|
||||
"network_id": "gitter",
|
||||
"desc": "Gitter",
|
||||
"icon": "mxc://example.org/zXyWvUt",
|
||||
"fields": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,18 @@
|
||||
# Copyright 2018 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.
|
||||
homeserverAccessToken:
|
||||
type: apiKey
|
||||
description: The `hs_token` provided by the application service's registration.
|
||||
name: access_token
|
||||
in: query
|
||||
@ -0,0 +1,33 @@
|
||||
# Copyright 2018 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.
|
||||
|
||||
# TODO: Change userid to user_id as a breaking change
|
||||
properties:
|
||||
userid:
|
||||
description: A Matrix User ID represting a third party user.
|
||||
type: string
|
||||
example: "@_gitter_jim:matrix.org"
|
||||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
type: string
|
||||
example: "gitter"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
type: object
|
||||
example: {
|
||||
"user": "jim"
|
||||
}
|
||||
required: ['userid', 'protocol', 'fields']
|
||||
title: User
|
||||
type: object
|
||||
@ -0,0 +1,17 @@
|
||||
# Copyright 2018 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.
|
||||
type: array
|
||||
description: List of matched third party users.
|
||||
items:
|
||||
$ref: user.yaml
|
||||
@ -0,0 +1,279 @@
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/app/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/thirdparty/protocol/{protocol}":
|
||||
get:
|
||||
summary: Retrieve metadata about a specific protocol that the application service supports.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to present clients
|
||||
with specific information about the various third party networks that
|
||||
an application service supports.
|
||||
operationId: getProtocolMetadata
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
responses:
|
||||
200:
|
||||
description: The protocol was found and metadata returned.
|
||||
schema:
|
||||
$ref: definitions/protocol_metadata.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No protocol was found with the given path.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/user/{protocol}":
|
||||
get:
|
||||
summary: Retrieve the Matrix User ID of a corresponding third party user.
|
||||
description: |-
|
||||
This API is called by the homeserver in order to retrieve a Matrix
|
||||
User ID linked to a user on the third party network, given a set of
|
||||
user parameters.
|
||||
operationId: queryUserByProtocol
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the user.
|
||||
responses:
|
||||
200:
|
||||
description: The Matrix User IDs found with the given parameters.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No users were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retrieve Matrix-side portal rooms leading to a third party location.
|
||||
description: |-
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
|
||||
operationId: queryLocationByProtocol
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the third party location.
|
||||
responses:
|
||||
200:
|
||||
description: At least one portal room was found.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/location":
|
||||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retrieve an array of third party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: alias
|
||||
type: string
|
||||
description: The Matrix room alias to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
All found third party locations.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/user":
|
||||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retrieve an array of third party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: userid
|
||||
type: string
|
||||
description: The Matrix User ID to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An array of third party users.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
@ -0,0 +1,90 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/app/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/rooms/{roomAlias}":
|
||||
get:
|
||||
summary: Query if a room alias should exist on the application service.
|
||||
description: |-
|
||||
This endpoint is invoked by the homeserver on an application service to query
|
||||
the existence of a given room alias. The homeserver will only query room
|
||||
aliases inside the application service's `aliases` namespace. The
|
||||
homeserver will send this request when it receives a request to join a
|
||||
room alias within the application service's namespace.
|
||||
operationId: queryRoomByAlias
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomAlias
|
||||
type: string
|
||||
description: The room alias being queried.
|
||||
required: true
|
||||
x-example: "#magicforest:example.com"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The application service indicates that this room alias exists. The
|
||||
application service MUST have created a room and associated it with
|
||||
the queried room alias using the client-server API. Additional
|
||||
information about the room such as its name and topic can be set
|
||||
before responding.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: |-
|
||||
The application service indicates that this room alias does not exist.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
@ -0,0 +1,87 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/app/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/users/{userId}":
|
||||
get:
|
||||
summary: Query if a user should exist on the application service.
|
||||
description: |-
|
||||
This endpoint is invoked by the homeserver on an application service to query
|
||||
the existence of a given user ID. The homeserver will only query user IDs
|
||||
inside the application service's `users` namespace. The homeserver will
|
||||
send this request when it receives an event for an unknown user ID in
|
||||
the application service's namespace, such as a room invite.
|
||||
operationId: queryUserById
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
type: string
|
||||
description: The user ID being queried.
|
||||
required: true
|
||||
x-example: "@alice:example.com"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The application service indicates that this user exists. The application
|
||||
service MUST create the user using the client-server API.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: |-
|
||||
The application service indicates that this user does not exist.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
@ -0,0 +1,77 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/app/v1
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/transactions/{txnId}":
|
||||
put:
|
||||
summary: Send some events to the application service.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to push an event
|
||||
(or batch of events) to the application service.
|
||||
|
||||
Note that the application service should distinguish state events
|
||||
from message events via the presence of a `state_key`, rather than
|
||||
via the event type.
|
||||
operationId: sendTransaction
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: txnId
|
||||
type: string
|
||||
description: |-
|
||||
The transaction ID for this set of events. Homeservers generate
|
||||
these IDs and they are used to ensure idempotency of requests.
|
||||
required: true
|
||||
x-example: "35"
|
||||
- in: body
|
||||
name: body
|
||||
description: Transaction information
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"events": [
|
||||
{"$ref": "../../event-schemas/examples/m.room.member.yaml"},
|
||||
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
|
||||
]
|
||||
}
|
||||
properties:
|
||||
events:
|
||||
type: array
|
||||
description: |-
|
||||
A list of events, formatted as per the Client-Server API.
|
||||
items:
|
||||
type: object
|
||||
title: Event
|
||||
required: ["events"]
|
||||
responses:
|
||||
200:
|
||||
description: The transaction was processed successfully.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
@ -0,0 +1,197 @@
|
||||
# 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 Client Config 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:
|
||||
"/user/{userId}/account_data/{type}":
|
||||
put:
|
||||
summary: Set some account_data for the user.
|
||||
description: |-
|
||||
Set some account_data for the client. This config is only visible to the user
|
||||
that set the account_data. The config will be synced to clients in the
|
||||
top-level `account_data`.
|
||||
operationId: setAccountData
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account_data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: type
|
||||
required: true
|
||||
description: |-
|
||||
The event type of the account_data to set. Custom types should be
|
||||
namespaced to avoid clashes.
|
||||
x-example: "org.example.custom.config"
|
||||
- in: body
|
||||
name: content
|
||||
required: true
|
||||
description: |-
|
||||
The content of the account_data
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"custom_account_data_key": "custom_config_value"}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The account_data was successfully added.
|
||||
tags:
|
||||
- User data
|
||||
get:
|
||||
summary: Get some account_data for the user.
|
||||
description: |-
|
||||
Get some account_data for the client. This config is only visible to the user
|
||||
that set the account_data.
|
||||
operationId: getAccountData
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account_data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: type
|
||||
required: true
|
||||
description: |-
|
||||
The event type of the account_data to get. Custom types should be
|
||||
namespaced to avoid clashes.
|
||||
x-example: "org.example.custom.config"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The account data content for the given type.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"custom_account_data_key": "custom_config_value"}
|
||||
tags:
|
||||
- User data
|
||||
"/user/{userId}/rooms/{roomId}/account_data/{type}":
|
||||
put:
|
||||
summary: Set some account_data for the user.
|
||||
description: |-
|
||||
Set some account_data for the client on a given room. This config is only
|
||||
visible to the user that set the account_data. The config will be synced to
|
||||
clients in the per-room `account_data`.
|
||||
operationId: setAccountDataPerRoom
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account_data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the room to set account_data on.
|
||||
x-example: "!726s6s6q:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: type
|
||||
required: true
|
||||
description: |-
|
||||
The event type of the account_data to set. Custom types should be
|
||||
namespaced to avoid clashes.
|
||||
x-example: "org.example.custom.room.config"
|
||||
- in: body
|
||||
name: content
|
||||
required: true
|
||||
description: |-
|
||||
The content of the account_data
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"custom_account_data_key": "custom_account_data_value"}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The account_data was successfully added.
|
||||
tags:
|
||||
- User data
|
||||
get:
|
||||
summary: Get some account_data for the user.
|
||||
description: |-
|
||||
Get some account_data for the client on a given room. This config is only
|
||||
visible to the user that set the account_data.
|
||||
operationId: getAccountDataPerRoom
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account_data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
required: true
|
||||
description: |-
|
||||
The ID of the room to get account_data for.
|
||||
x-example: "!726s6s6q:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: type
|
||||
required: true
|
||||
description: |-
|
||||
The event type of the account_data to get. Custom types should be
|
||||
namespaced to avoid clashes.
|
||||
x-example: "org.example.custom.room.config"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The account data content for the given type.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"custom_account_data_key": "custom_config_value"}
|
||||
tags:
|
||||
- User data
|
||||
@ -0,0 +1,115 @@
|
||||
# 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 Administration 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:
|
||||
"/admin/whois/{userId}":
|
||||
get:
|
||||
summary: Gets information about a particular user.
|
||||
description: |-
|
||||
Gets information about a particular user.
|
||||
|
||||
This API may be restricted to only be called by the user being looked
|
||||
up, or by a server admin. Server-local administrator privileges are not
|
||||
specified in this document.
|
||||
operationId: getWhoIs
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
description: The user to look up.
|
||||
required: true
|
||||
x-example: "@peter:rabbit.rocks"
|
||||
responses:
|
||||
200:
|
||||
description: The lookup was successful.
|
||||
examples:
|
||||
application/json: {
|
||||
"user_id": "@peter:rabbit.rocks",
|
||||
"devices": {
|
||||
"teapot": {
|
||||
"sessions": [
|
||||
{
|
||||
"connections": [
|
||||
{
|
||||
"ip": "127.0.0.1",
|
||||
"last_seen": 1411996332123,
|
||||
"user_agent": "curl/7.31.0-DEV"
|
||||
},
|
||||
{
|
||||
"ip": "10.0.0.2",
|
||||
"last_seen": 1411996332123,
|
||||
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The Matrix user ID of the user.
|
||||
devices:
|
||||
type: object
|
||||
description: |-
|
||||
Each key is an identifier for one of the user's devices.
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: DeviceInfo
|
||||
properties:
|
||||
sessions:
|
||||
type: array
|
||||
description: A user's sessions (i.e. what they did with an access token from one login).
|
||||
items:
|
||||
type: object
|
||||
title: SessionInfo
|
||||
properties:
|
||||
connections:
|
||||
type: array
|
||||
description: Information particular connections in the session.
|
||||
items:
|
||||
type: object
|
||||
title: ConnectionInfo
|
||||
properties:
|
||||
ip:
|
||||
type: string
|
||||
description: Most recently seen IP address of the session.
|
||||
last_seen:
|
||||
type: integer
|
||||
format: int64
|
||||
description: Unix timestamp that the session was last active.
|
||||
user_agent:
|
||||
type: string
|
||||
description: User agent string last seen in the session.
|
||||
tags:
|
||||
- Server administration
|
||||
@ -0,0 +1,517 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2019 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Account Administrative Contact 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:
|
||||
"/account/3pid":
|
||||
get:
|
||||
summary: Gets a list of a user's third party identifiers.
|
||||
description: |-
|
||||
Gets a list of the third party identifiers that the homeserver has
|
||||
associated with the user's account.
|
||||
|
||||
This is *not* the same as the list of third party identifiers bound to
|
||||
the user's Matrix ID in identity servers.
|
||||
|
||||
Identifiers in this list may be used by the homeserver as, for example,
|
||||
identifiers that it will accept to reset the user's account password.
|
||||
operationId: getAccount3PIDs
|
||||
security:
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The lookup was successful.
|
||||
examples:
|
||||
application/json: {
|
||||
"threepids": [
|
||||
{
|
||||
"medium": "email",
|
||||
"address": "monkey@banana.island",
|
||||
"validated_at": 1535176800000,
|
||||
"added_at": 1535336848756
|
||||
}
|
||||
]
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
threepids:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
title: Third party identifier
|
||||
properties:
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier.
|
||||
enum: ["email", "msisdn"]
|
||||
address:
|
||||
type: string
|
||||
description: The third party identifier address.
|
||||
validated_at:
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The timestamp, in milliseconds, when the identifier was
|
||||
validated by the identity server.
|
||||
added_at:
|
||||
type: integer
|
||||
format: int64
|
||||
description:
|
||||
The timestamp, in milliseconds, when the homeserver
|
||||
associated the third party identifier with the user.
|
||||
required: ['medium', 'address', 'validated_at', 'added_at']
|
||||
tags:
|
||||
- User data
|
||||
post:
|
||||
summary: Adds contact information to the user's account.
|
||||
description: |-
|
||||
Adds contact information to the user's account.
|
||||
|
||||
This endpoint is deprecated in favour of the more specific `/3pid/add`
|
||||
and `/3pid/bind` endpoints.
|
||||
|
||||
**Note:**
|
||||
Previously this endpoint supported a `bind` parameter. This parameter
|
||||
has been removed, making this endpoint behave as though it was `false`.
|
||||
This results in this endpoint being an equivalent to `/3pid/bind` rather
|
||||
than dual-purpose.
|
||||
operationId: post3PIDs
|
||||
deprecated: true
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
three_pid_creds:
|
||||
title: "ThreePidCredentials"
|
||||
type: object
|
||||
description: The third party credentials to associate with the account.
|
||||
properties:
|
||||
client_secret:
|
||||
type: string
|
||||
description: The client secret used in the session with the identity server.
|
||||
id_server:
|
||||
type: string
|
||||
description: The identity server to use.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
sid:
|
||||
type: string
|
||||
description: The session identifier given by the identity server.
|
||||
required: ["client_secret", "id_server", "id_access_token", "sid"]
|
||||
required: ["three_pid_creds"]
|
||||
example: {
|
||||
"three_pid_creds": {
|
||||
"id_server": "matrix.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"sid": "abc123987",
|
||||
"client_secret": "d0n'tT3ll"
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The addition was successful.
|
||||
examples:
|
||||
application/json: {
|
||||
"submit_url": "https://example.org/path/to/submitToken"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
submit_url:
|
||||
type: string
|
||||
description: |-
|
||||
An optional field containing a URL where the client must
|
||||
submit the validation token to, with identical parameters
|
||||
to the Identity Service API's `POST
|
||||
/validate/email/submitToken` endpoint (without the requirement
|
||||
for an access token). The homeserver must send this token to the
|
||||
user (if applicable), who should then be prompted to provide it
|
||||
to the client.
|
||||
|
||||
If this field is not present, the client can assume that
|
||||
verification will happen without the client's involvement
|
||||
provided the homeserver advertises this specification version
|
||||
in the `/versions` response (ie: r0.5.0).
|
||||
example: "https://example.org/path/to/submitToken"
|
||||
403:
|
||||
description: The credentials could not be verified with the identity server.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_AUTH_FAILED",
|
||||
"error": "The third party credentials could not be verified by the identity server."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- User data
|
||||
"/account/3pid/add":
|
||||
post:
|
||||
summary: Adds contact information to the user's account.
|
||||
description: |-
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
Adds contact information to the user's account. Homeservers should use 3PIDs added
|
||||
through this endpoint for password resets instead of relying on the identity server.
|
||||
|
||||
Homeservers should prevent the caller from adding a 3PID to their account if it has
|
||||
already been added to another user's account on the homeserver.
|
||||
operationId: add3PID
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: |-
|
||||
Additional authentication information for the
|
||||
user-interactive authentication API.
|
||||
allOf:
|
||||
- $ref: "definitions/auth_data.yaml"
|
||||
client_secret:
|
||||
type: string
|
||||
description: The client secret used in the session with the homeserver.
|
||||
sid:
|
||||
type: string
|
||||
description: The session identifier given by the homeserver.
|
||||
required: ["client_secret", "sid"]
|
||||
example: {
|
||||
"sid": "abc123987",
|
||||
"client_secret": "d0n'tT3ll"
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The addition was successful.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
"/account/3pid/bind":
|
||||
post:
|
||||
summary: Binds a 3PID to the user's account through an Identity Service.
|
||||
description: |-
|
||||
Binds a 3PID to the user's account through the specified identity server.
|
||||
|
||||
Homeservers should not prevent this request from succeeding if another user
|
||||
has bound the 3PID. Homeservers should simply proxy any errors received by
|
||||
the identity server to the caller.
|
||||
|
||||
Homeservers should track successful binds so they can be unbound later.
|
||||
operationId: bind3PID
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
client_secret:
|
||||
type: string
|
||||
description: The client secret used in the session with the identity server.
|
||||
id_server:
|
||||
type: string
|
||||
description: The identity server to use.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server.
|
||||
sid:
|
||||
type: string
|
||||
description: The session identifier given by the identity server.
|
||||
required: ["client_secret", "id_server", "id_access_token", "sid"]
|
||||
example: {
|
||||
"id_server": "example.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"sid": "abc123987",
|
||||
"client_secret": "d0n'tT3ll"
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The addition was successful.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- User data
|
||||
"/account/3pid/delete":
|
||||
post:
|
||||
summary: Deletes a third party identifier from the user's account
|
||||
description: |-
|
||||
Removes a third party identifier from the user's account. This might not
|
||||
cause an unbind of the identifier from the identity server.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
operationId: delete3pidFromAccount
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind from. If not provided, the homeserver
|
||||
MUST use the `id_server` the identifier was added through. If the
|
||||
homeserver does not know the original `id_server`, it MUST return
|
||||
a `id_server_unbind_result` of `no-support`.
|
||||
example: "example.org"
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier being removed.
|
||||
enum: ["email", "msisdn"]
|
||||
example: "email"
|
||||
address:
|
||||
type: string
|
||||
description: The third party address being removed.
|
||||
example: "example@example.org"
|
||||
required: ['medium', 'address']
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The homeserver has disassociated the third party identifier from the
|
||||
user.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
# XXX: I don't know why, but the order matters here so that "no-support"
|
||||
# doesn't become "no- support" by the renderer.
|
||||
- "no-support"
|
||||
- "success"
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the 3PID from the identity server. `success` indicates that the
|
||||
indentity server has unbound the identifier whereas `no-support`
|
||||
indicates that the identity server refuses to support the request
|
||||
or the homeserver was not able to determine an identity server to
|
||||
unbind from.
|
||||
example: "success"
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
tags:
|
||||
- User data
|
||||
"/account/3pid/unbind":
|
||||
post:
|
||||
summary: Removes a user's third party identifier from an identity server.
|
||||
description: |-
|
||||
Removes a user's third party identifier from the provided identity server
|
||||
without removing it from the homeserver.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
operationId: unbind3pidFromAccount
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind from. If not provided, the homeserver
|
||||
MUST use the `id_server` the identifier was added through. If the
|
||||
homeserver does not know the original `id_server`, it MUST return
|
||||
a `id_server_unbind_result` of `no-support`.
|
||||
example: "example.org"
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier being removed.
|
||||
enum: ["email", "msisdn"]
|
||||
example: "email"
|
||||
address:
|
||||
type: string
|
||||
description: The third party address being removed.
|
||||
example: "example@example.org"
|
||||
required: ['medium', 'address']
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The identity server has disassociated the third party identifier from the
|
||||
user.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
# XXX: I don't know why, but the order matters here so that "no-support"
|
||||
# doesn't become "no- support" by the renderer.
|
||||
- "no-support"
|
||||
- "success"
|
||||
description: |-
|
||||
An indicator as to whether or not the identity server was able to unbind
|
||||
the 3PID. `success` indicates that the identity server has unbound the
|
||||
identifier whereas `no-support` indicates that the identity server
|
||||
refuses to support the request or the homeserver was not able to determine
|
||||
an identity server to unbind from.
|
||||
example: "success"
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
tags:
|
||||
- User data
|
||||
"/account/3pid/email/requestToken":
|
||||
post:
|
||||
summary: Begins the validation process for an email address for association with the user's account.
|
||||
description: |-
|
||||
The homeserver must check that the given email address is **not**
|
||||
already associated with an account on this homeserver. This API should
|
||||
be used to request validation tokens when adding an email address to an
|
||||
account. This API's parameters and response are identical to that of
|
||||
the [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken)
|
||||
endpoint. The homeserver should validate
|
||||
the email itself, either by sending a validation email itself or by using
|
||||
a service it has control over.
|
||||
operationId: requestTokenTo3PIDEmail
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_email_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An email was sent to the given address. Note that this may be an
|
||||
email containing the validation token or it may be informing the
|
||||
user of an error.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The third party identifier is already in use on the homeserver, or
|
||||
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "Third party identifier already in use"
|
||||
}
|
||||
"/account/3pid/msisdn/requestToken":
|
||||
post:
|
||||
summary: Begins the validation process for a phone number for association with the user's account.
|
||||
description: |-
|
||||
The homeserver must check that the given phone number is **not**
|
||||
already associated with an account on this homeserver. This API should
|
||||
be used to request validation tokens when adding a phone number to an
|
||||
account. This API's parameters and response are identical to that of
|
||||
the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken)
|
||||
endpoint. The homeserver should validate
|
||||
the phone number itself, either by sending a validation message itself or by using
|
||||
a service it has control over.
|
||||
operationId: requestTokenTo3PIDMSISDN
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_msisdn_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: An SMS message was sent to the given phone number.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The third party identifier is already in use on the homeserver, or
|
||||
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "Third party identifier already in use"
|
||||
}
|
||||
@ -0,0 +1,88 @@
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Application Service Room Directory API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
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:
|
||||
"/directory/list/appservice/{networkId}/{roomId}":
|
||||
put:
|
||||
summary: |-
|
||||
Updates a room's visibility in the application service's room directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room on the application service's room
|
||||
directory.
|
||||
|
||||
This API is similar to the room directory visibility API used by clients
|
||||
to update the homeserver's more general room directory.
|
||||
|
||||
This API requires the use of an application service access token (`as_token`)
|
||||
instead of a typical client's access_token. This API cannot be invoked by
|
||||
users who are not identified as application services.
|
||||
operationId: updateAppserviceRoomDirectoryVsibility
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: networkId
|
||||
description: |-
|
||||
The protocol (network) ID to update the room list for. This would
|
||||
have been provided by the application service as being listed as
|
||||
a supported protocol.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room ID to add to the directory.
|
||||
required: true
|
||||
x-example: "!somewhere:example.org"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
visibility:
|
||||
type: string
|
||||
enum: ["public", "private"]
|
||||
description: |-
|
||||
Whether the room should be visible (public) in the directory
|
||||
or not (private).
|
||||
example: "public"
|
||||
required: ['visibility']
|
||||
security:
|
||||
# again, this is the appservice's token - not a typical client's
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The room's directory visibility has been updated.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: {}
|
||||
tags:
|
||||
- Application service room directory management
|
||||
@ -0,0 +1,148 @@
|
||||
# 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 Room Banning 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}/ban":
|
||||
post:
|
||||
summary: Ban a user in the room.
|
||||
description: |-
|
||||
Ban a user in the room. If the user is currently in the room, also kick them.
|
||||
|
||||
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
|
||||
|
||||
The caller must have the required power level in order to perform this operation.
|
||||
operationId: ban
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room identifier (not alias) from which the user should be banned.
|
||||
required: true
|
||||
x-example: "!e42d8c:matrix.org"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"reason": "Telling unfunny jokes",
|
||||
"user_id": "@cheeky_monkey:matrix.org"
|
||||
}
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The fully qualified user ID of the user being banned.
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the user has been banned. This will be supplied as the
|
||||
`reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
|
||||
required: ["user_id"]
|
||||
responses:
|
||||
200:
|
||||
description: The user has been kicked and banned from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
403:
|
||||
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:
|
||||
|
||||
- The banner is not currently in the room.
|
||||
- The banner's power level is insufficient to ban users from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You do not have a high enough power level to ban from this room."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
"/rooms/{roomId}/unban":
|
||||
post:
|
||||
summary: Unban a user from the room.
|
||||
description: |-
|
||||
Unban a user from the room. This allows them to be invited to the room,
|
||||
and join if they would otherwise be allowed to join according to its join rules.
|
||||
|
||||
The caller must have the required power level in order to perform this operation.
|
||||
operationId: unban
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room identifier (not alias) from which the user should be unbanned.
|
||||
required: true
|
||||
x-example: "!e42d8c:matrix.org"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"user_id": "@cheeky_monkey:matrix.org",
|
||||
"reason": "They've been banned long enough"
|
||||
}
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The fully qualified user ID of the user being unbanned.
|
||||
reason:
|
||||
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 unbanned from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
403:
|
||||
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:
|
||||
|
||||
- The unbanner's power level is insufficient to unban users from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You do not have a high enough power level to unban from this room."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
@ -0,0 +1,112 @@
|
||||
# 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Capabilities API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/capabilities":
|
||||
get:
|
||||
summary: Gets information about the server's capabilities.
|
||||
description: |-
|
||||
Gets information about the server's supported feature set
|
||||
and other relevant capabilities.
|
||||
operationId: getCapabilities
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters: []
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The capabilities of the server.
|
||||
examples:
|
||||
application/json: {
|
||||
"capabilities": {
|
||||
"m.change_password": {
|
||||
"enabled": false
|
||||
},
|
||||
"m.room_versions": {
|
||||
"default": "1",
|
||||
"available": {
|
||||
"1": "stable",
|
||||
"2": "stable",
|
||||
"3": "unstable",
|
||||
"test-version": "unstable"
|
||||
}
|
||||
},
|
||||
"com.example.custom.ratelimit": {
|
||||
"max_requests_per_hour": 600
|
||||
}
|
||||
}
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
required: ["capabilities"]
|
||||
properties:
|
||||
capabilities:
|
||||
type: object
|
||||
title: Capabilities
|
||||
description: |-
|
||||
The custom capabilities the server supports, using the
|
||||
Java package naming convention.
|
||||
additionalProperties:
|
||||
type: object
|
||||
properties:
|
||||
"m.change_password":
|
||||
type: object
|
||||
description: |-
|
||||
Capability to indicate if the user can change their password.
|
||||
title: ChangePasswordCapability
|
||||
properties:
|
||||
enabled:
|
||||
type: boolean
|
||||
description: |-
|
||||
True if the user can change their password, false otherwise.
|
||||
example: false
|
||||
required: ['enabled']
|
||||
"m.room_versions":
|
||||
type: object
|
||||
description: The room versions the server supports.
|
||||
title: RoomVersionsCapability
|
||||
properties:
|
||||
default:
|
||||
type: string
|
||||
description: |-
|
||||
The default room version the server is using for new rooms.
|
||||
example: "1"
|
||||
available:
|
||||
type: object
|
||||
description: |-
|
||||
A detailed description of the room versions the server supports.
|
||||
additionalProperties:
|
||||
type: string
|
||||
title: RoomVersionStability
|
||||
enum: [stable, unstable]
|
||||
description: The stability of the room version.
|
||||
required: ['default', 'available']
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Capabilities
|
||||
@ -0,0 +1,451 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2019 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Content Repository API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
- "*/*"
|
||||
produces:
|
||||
- application/json
|
||||
- "*/*"
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/upload":
|
||||
post:
|
||||
summary: Upload some content to the content repository.
|
||||
operationId: uploadContent
|
||||
produces: ["application/json"]
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: header
|
||||
name: Content-Type
|
||||
type: string
|
||||
description: The content type of the file being uploaded
|
||||
x-example: "application/pdf"
|
||||
- in: query
|
||||
type: string
|
||||
x-example: "War and Peace.pdf"
|
||||
name: filename
|
||||
description: The name of the file being uploaded
|
||||
- in: body
|
||||
name: "<content>"
|
||||
description: The content to be uploaded.
|
||||
required: true
|
||||
x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
|
||||
schema:
|
||||
type: string
|
||||
example: "<bytes>"
|
||||
format: byte
|
||||
responses:
|
||||
200:
|
||||
description: The [MXC URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content.
|
||||
schema:
|
||||
type: object
|
||||
required: ["content_uri"]
|
||||
properties:
|
||||
content_uri:
|
||||
type: string
|
||||
description: "The [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content."
|
||||
examples:
|
||||
application/json: {
|
||||
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
|
||||
}
|
||||
403:
|
||||
description: |-
|
||||
The user does not have permission to upload the content. Some reasons for this error include:
|
||||
|
||||
- The server does not permit the file type.
|
||||
- The user has reached a quota for uploaded content.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Cannot upload this content"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
413:
|
||||
description: |-
|
||||
The uploaded content is too large for the server.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_TOO_LARGE",
|
||||
"error": "Cannot upload files larger than 100mb"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Media
|
||||
"/download/{serverName}/{mediaId}":
|
||||
get:
|
||||
summary: "Download content from the content repository."
|
||||
operationId: getContent
|
||||
produces: ["*/*"]
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: serverName
|
||||
x-example: matrix.org
|
||||
required: true
|
||||
description: |
|
||||
The server name from the `mxc://` URI (the authoritory component)
|
||||
- in: path
|
||||
type: string
|
||||
name: mediaId
|
||||
x-example: ascERGshawAWawugaAcauga
|
||||
required: true
|
||||
description: |
|
||||
The media ID from the `mxc://` URI (the path component)
|
||||
- in: query
|
||||
type: boolean
|
||||
name: allow_remote
|
||||
x-example: false
|
||||
required: false
|
||||
default: true
|
||||
description: |
|
||||
Indicates to the server that it should not attempt to fetch the media if it is deemed
|
||||
remote. This is to prevent routing loops where the server contacts itself. Defaults to
|
||||
true if not provided.
|
||||
responses:
|
||||
200:
|
||||
description: "The content that was previously uploaded."
|
||||
headers:
|
||||
Content-Type:
|
||||
description: "The content type of the file that was previously uploaded."
|
||||
type: "string"
|
||||
Content-Disposition:
|
||||
description: |-
|
||||
The name of the file that was previously uploaded, if set.
|
||||
type: "string"
|
||||
schema:
|
||||
type: file
|
||||
# This is a workaround for us not being able to say the response is required.
|
||||
description: "**Required.** The bytes for the uploaded file."
|
||||
502:
|
||||
description: |-
|
||||
The content is too large for the server to serve.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_TOO_LARGE",
|
||||
"error": "Content is too large to serve"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Media
|
||||
"/download/{serverName}/{mediaId}/{fileName}":
|
||||
get:
|
||||
summary: Download content from the content repository overriding the file name
|
||||
description: |-
|
||||
This will download content from the content repository (same as
|
||||
the previous endpoint) but replace the target file name with the one
|
||||
provided by the caller.
|
||||
operationId: getContentOverrideName
|
||||
produces: ["*/*"]
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: serverName
|
||||
x-example: matrix.org
|
||||
required: true
|
||||
description: |
|
||||
The server name from the `mxc://` URI (the authoritory component)
|
||||
- in: path
|
||||
type: string
|
||||
name: mediaId
|
||||
x-example: ascERGshawAWawugaAcauga
|
||||
required: true
|
||||
description: |
|
||||
The media ID from the `mxc://` URI (the path component)
|
||||
- in: path
|
||||
type: string
|
||||
name: fileName
|
||||
x-example: filename.jpg
|
||||
required: true
|
||||
description: A filename to give in the `Content-Disposition` header.
|
||||
- in: query
|
||||
type: boolean
|
||||
name: allow_remote
|
||||
x-example: false
|
||||
required: false
|
||||
default: true
|
||||
description: |
|
||||
Indicates to the server that it should not attempt to fetch the media if it is deemed
|
||||
remote. This is to prevent routing loops where the server contacts itself. Defaults to
|
||||
true if not provided.
|
||||
responses:
|
||||
200:
|
||||
description: "The content that was previously uploaded."
|
||||
headers:
|
||||
Content-Type:
|
||||
description: "The content type of the file that was previously uploaded."
|
||||
type: "string"
|
||||
Content-Disposition:
|
||||
description: |-
|
||||
The `fileName` requested or the name of the file that was previously
|
||||
uploaded, if set.
|
||||
type: "string"
|
||||
schema:
|
||||
type: file
|
||||
# This is a workaround for us not being able to say the response is required.
|
||||
description: "**Required.** The bytes for the uploaded file."
|
||||
502:
|
||||
description: |-
|
||||
The content is too large for the server to serve.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_TOO_LARGE",
|
||||
"error": "Content is too large to serve"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Media
|
||||
"/thumbnail/{serverName}/{mediaId}":
|
||||
get:
|
||||
summary: Download a thumbnail of content from the content repository
|
||||
description: |-
|
||||
Download a thumbnail of content from the content repository.
|
||||
See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
|
||||
operationId: getContentThumbnail
|
||||
produces: ["image/jpeg", "image/png"]
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: serverName
|
||||
required: true
|
||||
x-example: example.org
|
||||
description: |
|
||||
The server name from the `mxc://` URI (the authoritory component)
|
||||
- in: path
|
||||
type: string
|
||||
name: mediaId
|
||||
x-example: ascERGshawAWawugaAcauga
|
||||
required: true
|
||||
description: |
|
||||
The media ID from the `mxc://` URI (the path component)
|
||||
- in: query
|
||||
type: integer
|
||||
x-example: 64
|
||||
name: width
|
||||
required: true
|
||||
description: |-
|
||||
The *desired* width of the thumbnail. The actual thumbnail may be
|
||||
larger than the size specified.
|
||||
- in: query
|
||||
type: integer
|
||||
x-example: 64
|
||||
name: height
|
||||
required: true
|
||||
description: |-
|
||||
The *desired* height of the thumbnail. The actual thumbnail may be
|
||||
larger than the size specified.
|
||||
- in: query
|
||||
type: string
|
||||
enum: ["crop", "scale"]
|
||||
name: method
|
||||
x-example: "scale"
|
||||
description: |-
|
||||
The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails)
|
||||
section for more information.
|
||||
- in: query
|
||||
type: boolean
|
||||
name: allow_remote
|
||||
x-example: false
|
||||
required: false
|
||||
default: true
|
||||
description: |-
|
||||
Indicates to the server that it should not attempt to fetch
|
||||
the media if it is deemed remote. This is to prevent routing loops
|
||||
where the server contacts itself. Defaults to true if not provided.
|
||||
responses:
|
||||
200:
|
||||
description: "A thumbnail of the requested content."
|
||||
headers:
|
||||
Content-Type:
|
||||
description: "The content type of the thumbnail."
|
||||
type: "string"
|
||||
enum: ["image/jpeg", "image/png"]
|
||||
schema:
|
||||
type: file
|
||||
# This is a workaround for us not being able to say the response is required.
|
||||
description: "**Required.** The bytes for the thumbnail."
|
||||
400:
|
||||
description: |-
|
||||
The request does not make sense to the server, or the server cannot thumbnail
|
||||
the content. For example, the client requested non-integer dimensions or asked
|
||||
for negatively-sized images.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_UNKNOWN",
|
||||
"error": "Cannot generate thumbnails for the requested content"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
413:
|
||||
description: |-
|
||||
The local content is too large for the server to thumbnail.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_TOO_LARGE",
|
||||
"error": "Content is too large to thumbnail"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
502:
|
||||
description: |-
|
||||
The remote content is too large for the server to thumbnail.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_TOO_LARGE",
|
||||
"error": "Content is too large to thumbnail"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Media
|
||||
"/preview_url":
|
||||
get:
|
||||
summary: "Get information about a URL for a client"
|
||||
description: |-
|
||||
Get information about a URL for the client. Typically this is called when a
|
||||
client sees a URL in a message and wants to render a preview for the user.
|
||||
|
||||
**Note:**
|
||||
Clients should consider avoiding this endpoint for URLs posted in encrypted
|
||||
rooms. Encrypted rooms often contain more sensitive information the users
|
||||
do not want to share with the homeserver, and this can mean that the URLs
|
||||
being shared should also not be shared with the homeserver.
|
||||
|
||||
operationId: getUrlPreview
|
||||
produces: ["application/json"]
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
x-example: "https://matrix.org"
|
||||
name: url
|
||||
description: "The URL to get a preview of."
|
||||
required: true
|
||||
- in: query
|
||||
type: integer
|
||||
format: int64
|
||||
x-example: 1510610716656
|
||||
name: ts
|
||||
description: |-
|
||||
The preferred point in time to return a preview for. The server may
|
||||
return a newer version if it does not have the requested version
|
||||
available.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The OpenGraph data for the URL, which may be empty. Some values are
|
||||
replaced with matrix equivalents if they are provided in the response.
|
||||
The differences from the OpenGraph protocol are described here.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
"matrix:image:size":
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The byte-size of the image. Omitted if there is no image attached.
|
||||
"og:image":
|
||||
type: string
|
||||
description: |-
|
||||
An [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image.
|
||||
examples:
|
||||
application/json: {
|
||||
"og:title": "Matrix Blog Post",
|
||||
"og:description": "This is a really cool blog post from matrix.org",
|
||||
"og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
|
||||
"og:image:type": "image/png",
|
||||
"og:image:height": 48,
|
||||
"og:image:width": 48,
|
||||
"matrix:image:size": 102400
|
||||
}
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Media
|
||||
"/config":
|
||||
get:
|
||||
summary: Get the configuration for the content repository.
|
||||
description: |-
|
||||
This endpoint allows clients to retrieve the configuration of the content
|
||||
repository, such as upload limitations.
|
||||
Clients SHOULD use this as a guide when using content repository endpoints.
|
||||
All values are intentionally left optional. Clients SHOULD follow
|
||||
the advice given in the field description when the field is not available.
|
||||
|
||||
**NOTE:** Both clients and server administrators should be aware that proxies
|
||||
between the client and the server may affect the apparent behaviour of content
|
||||
repository APIs, for example, proxies may enforce a lower upload size limit
|
||||
than is advertised by the server on this endpoint.
|
||||
operationId: getConfig
|
||||
produces: ["application/json"]
|
||||
security:
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The public content repository configuration for the matrix server.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
m.upload.size:
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The maximum size an upload can be in bytes.
|
||||
Clients SHOULD use this as a guide when uploading content.
|
||||
If not listed or null, the size limit should be treated as unknown.
|
||||
examples:
|
||||
application/json: {
|
||||
"m.upload.size": 50000000
|
||||
}
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
|
||||
tags:
|
||||
- Media
|
||||
@ -0,0 +1,268 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Room Creation 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:
|
||||
"/createRoom":
|
||||
post:
|
||||
summary: Create a new room
|
||||
description: |-
|
||||
Create a new room with various configuration options.
|
||||
|
||||
The server MUST apply the normal state resolution rules when creating
|
||||
the new room, including checking power levels for each event. It MUST
|
||||
apply the events implied by the request in the following order:
|
||||
|
||||
1. The `m.room.create` event itself. Must be the first event in the
|
||||
room.
|
||||
|
||||
2. An `m.room.member` event for the creator to join the room. This is
|
||||
needed so the remaining events can be sent.
|
||||
|
||||
3. A default `m.room.power_levels` event, giving the room creator
|
||||
(and not other members) permission to send state events. Overridden
|
||||
by the `power_level_content_override` parameter.
|
||||
|
||||
4. Events set by the `preset`. Currently these are the `m.room.join_rules`,
|
||||
`m.room.history_visibility`, and `m.room.guest_access` state events.
|
||||
|
||||
5. Events listed in `initial_state`, in the order that they are
|
||||
listed.
|
||||
|
||||
6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic`
|
||||
state events).
|
||||
|
||||
7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with
|
||||
`membership: invite` and `m.room.third_party_invite`).
|
||||
|
||||
The available presets do the following with respect to room state:
|
||||
|
||||
| Preset | `join_rules` | `history_visibility` | `guest_access` | Other |
|
||||
|------------------------|--------------|----------------------|----------------|-------|
|
||||
| `private_chat` | `invite` | `shared` | `can_join` | |
|
||||
| `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. |
|
||||
| `public_chat` | `public` | `shared` | `forbidden` | |
|
||||
|
||||
The server will create a `m.room.create` event in the room with the
|
||||
requesting user as the creator, alongside other keys provided in the
|
||||
`creation_content`.
|
||||
operationId: createRoom
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
description: The desired room configuration.
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"preset": "public_chat",
|
||||
"room_alias_name": "thepub",
|
||||
"name": "The Grand Duke Pub",
|
||||
"topic": "All about happy hour",
|
||||
"creation_content": {
|
||||
"m.federate": false
|
||||
}
|
||||
}
|
||||
properties:
|
||||
visibility:
|
||||
type: string
|
||||
enum: ["public", "private"]
|
||||
description: |-
|
||||
A `public` visibility indicates that the room will be shown
|
||||
in the published room list. A `private` visibility will hide
|
||||
the room from the published room list. Rooms default to
|
||||
`private` visibility if this key is not included. NB: This
|
||||
should not be confused with `join_rules` which also uses the
|
||||
word `public`.
|
||||
room_alias_name:
|
||||
type: string
|
||||
description: |-
|
||||
The desired room alias **local part**. If this is included, a
|
||||
room alias will be created and mapped to the newly created
|
||||
room. The alias will belong on the *same* homeserver which
|
||||
created the room. For example, if this was set to "foo" and
|
||||
sent to the homeserver "example.com" the complete room alias
|
||||
would be `#foo:example.com`.
|
||||
|
||||
The complete room alias will become the canonical alias for
|
||||
the room.
|
||||
name:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.name` event will be sent
|
||||
into the room to indicate the name of the room. See Room
|
||||
Events for more information on `m.room.name`.
|
||||
topic:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.topic` event will be sent
|
||||
into the room to indicate the topic for the room. See Room
|
||||
Events for more information on `m.room.topic`.
|
||||
invite:
|
||||
type: array
|
||||
description: |-
|
||||
A list of user IDs to invite to the room. This will tell the
|
||||
server to invite everyone in the list to the newly created room.
|
||||
items:
|
||||
type: string
|
||||
invite_3pid:
|
||||
type: array
|
||||
description: |-
|
||||
A list of objects representing third party IDs to invite into
|
||||
the room.
|
||||
items:
|
||||
type: object
|
||||
title: Invite3pid
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: The hostname+port of the identity server which should be used for third party identifier lookups.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
medium:
|
||||
type: string
|
||||
# TODO: Link to Identity Service spec when it eixsts
|
||||
description: The kind of address being passed in the address field, for example `email`.
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third party identifier.
|
||||
required: ["id_server", "id_access_token", "medium", "address"]
|
||||
room_version:
|
||||
type: string
|
||||
description: |-
|
||||
The room version to set for the room. If not provided, the homeserver is
|
||||
to use its configured default. If provided, the homeserver will return a
|
||||
400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not
|
||||
support the room version.
|
||||
example: "1"
|
||||
creation_content:
|
||||
title: CreationContent
|
||||
type: object
|
||||
description: |-
|
||||
Extra keys, such as `m.federate`, to be added to the content
|
||||
of the [`m.room.create`](client-server-api/#mroomcreate) event. The server will clobber the following
|
||||
keys: `creator`, `room_version`. Future versions of the specification
|
||||
may allow the server to clobber other keys.
|
||||
initial_state:
|
||||
type: array
|
||||
description: |-
|
||||
A list of state events to set in the new room. This allows
|
||||
the user to override the default state events set in the new
|
||||
room. The expected format of the state events are an object
|
||||
with type, state_key and content keys set.
|
||||
|
||||
Takes precedence over events set by `preset`, but gets
|
||||
overriden by `name` and `topic` keys.
|
||||
items:
|
||||
type: object
|
||||
title: StateEvent
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: The type of event to send.
|
||||
state_key:
|
||||
type: string
|
||||
description: The state_key of the state event. Defaults to an empty string.
|
||||
content:
|
||||
type: object
|
||||
description: The content of the event.
|
||||
required: ["type", "content"]
|
||||
preset:
|
||||
type: string
|
||||
enum: ["private_chat", "public_chat", "trusted_private_chat"]
|
||||
description: |-
|
||||
Convenience parameter for setting various default state events
|
||||
based on a preset.
|
||||
|
||||
If unspecified, the server should use the `visibility` to determine
|
||||
which preset to use. A visbility of `public` equates to a preset of
|
||||
`public_chat` and `private` visibility equates to a preset of
|
||||
`private_chat`.
|
||||
is_direct:
|
||||
type: boolean
|
||||
description: |-
|
||||
This flag makes the server set the `is_direct` flag on the
|
||||
`m.room.member` events sent to the users in `invite` and
|
||||
`invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
|
||||
power_level_content_override:
|
||||
title: Power Level Event Content
|
||||
type: object
|
||||
description: |-
|
||||
The power level content to override in the default power level
|
||||
event. This object is applied on top of the generated
|
||||
[`m.room.power_levels`](client-server-api/#mroompower_levels)
|
||||
event content prior to it being sent to the room. Defaults to
|
||||
overriding nothing.
|
||||
responses:
|
||||
200:
|
||||
description: Information about the newly created room.
|
||||
schema:
|
||||
type: object
|
||||
description: Information about the newly created room.
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: |-
|
||||
The created room's ID.
|
||||
required: ['room_id']
|
||||
examples:
|
||||
application/json: {
|
||||
"room_id": "!sefiuhWgwghwWgh:example.com"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
|
||||
The request is invalid. A meaningful `errcode` and description
|
||||
error text will be returned. Example reasons for rejection include:
|
||||
|
||||
- The request body is malformed (`errcode` set to `M_BAD_JSON`
|
||||
or `M_NOT_JSON`).
|
||||
|
||||
- The room alias specified is already taken (`errcode` set to
|
||||
`M_ROOM_IN_USE`).
|
||||
|
||||
- The initial state implied by the parameters to the request is
|
||||
invalid: for example, the user's `power_level` is set below
|
||||
that necessary to set the room name (`errcode` set to
|
||||
`M_INVALID_ROOM_STATE`).
|
||||
|
||||
- The homeserver doesn't support the requested room version, or
|
||||
one or more users being invited to the new room are residents
|
||||
of a homeserver which does not support the requested room version.
|
||||
The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these
|
||||
cases.
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room creation
|
||||
@ -0,0 +1,224 @@
|
||||
# Copyright 2020 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Cross Signing 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:
|
||||
"/keys/device_signing/upload":
|
||||
post:
|
||||
summary: Upload cross-signing keys.
|
||||
description: |-
|
||||
Publishes cross-signing keys for the user.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
operationId: uploadCrossSigningKeys
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: keys
|
||||
description: |-
|
||||
The keys to be published.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
master_key:
|
||||
description: |-
|
||||
Optional. The user\'s master key.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
self_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s self-signing key. Must be signed by
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
user_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s user-signing key. Must be signed by
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"master_key": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["master"],
|
||||
"keys": {
|
||||
"ed25519:base64+master+public+key": "base64+master+public+key",
|
||||
}
|
||||
},
|
||||
"self_signing_key": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["self_signing"],
|
||||
"keys": {
|
||||
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
|
||||
}
|
||||
}
|
||||
},
|
||||
"user_signing_key": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["user_signing"],
|
||||
"keys": {
|
||||
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The provided keys were successfully uploaded.
|
||||
schema:
|
||||
type: object
|
||||
example: {}
|
||||
400:
|
||||
description: |-
|
||||
The input was invalid in some way. This can include one of the
|
||||
following error codes:
|
||||
|
||||
* `M_INVALID_SIGNATURE`: For example, the self-signing or
|
||||
user-signing key had an incorrect signature.
|
||||
* `M_MISSING_PARAM`: No master key is available.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"errcode": "M_INVALID_SIGNATURE",
|
||||
"error": "Invalid signature"
|
||||
}
|
||||
403:
|
||||
description: |-
|
||||
The public key of one of the keys is the same as one of the user\'s
|
||||
device IDs, or the request is not authorized for any other reason.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Key ID in use"
|
||||
}
|
||||
"/keys/signatures/upload":
|
||||
post:
|
||||
summary: Upload cross-signing signatures.
|
||||
description: |-
|
||||
Publishes cross-signing signatures for the user. The request body is a
|
||||
map from user ID to key ID to signed JSON object.
|
||||
operationId: uploadCrossSigningSignatures
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: signatures
|
||||
description: |-
|
||||
The signatures to be published.
|
||||
schema:
|
||||
type: object
|
||||
title: Signatures
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"HIJKLMN": {
|
||||
"user_id": "@alice:example.com",
|
||||
"device_id": "HIJKLMN",
|
||||
"algorithms": [
|
||||
"m.olm.curve25519-aes-sha256",
|
||||
"m.megolm.v1.aes-sha"
|
||||
],
|
||||
"keys": {
|
||||
"curve25519:HIJKLMN": "base64+curve25519+key",
|
||||
"ed25519:HIJKLMN": "base64+ed25519+key"
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
|
||||
}
|
||||
}
|
||||
},
|
||||
"base64+master+public+key": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["master"],
|
||||
"keys": {
|
||||
"ed25519:base64+master+public+key": "base64+master+public+key"
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:HIJKLMN": "base64+signature+of+master+key"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"@bob:example.com": {
|
||||
"bobs+base64+master+public+key": {
|
||||
"user_id": "@bob:example.com",
|
||||
"keys": {
|
||||
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
|
||||
},
|
||||
"usage": ["master"],
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The provided signatures were processed.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
failures:
|
||||
type: object
|
||||
description: |-
|
||||
A map from user ID to key ID to an error for any signatures
|
||||
that failed. If a signature was invalid, the `errcode` will
|
||||
be set to `M_INVALID_SIGNATURE`.
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Error
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"HIJKLMN": {
|
||||
"errcode": "M_INVALID_SIGNATURE",
|
||||
"error": "Invalid signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,33 @@
|
||||
# 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.
|
||||
title: Authentication Data
|
||||
description: |-
|
||||
Used by clients to submit authentication information to the interactive-authentication API
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
description: The login type that the client is attempting to complete.
|
||||
type: string
|
||||
session:
|
||||
description: The value of the session key given by the homeserver.
|
||||
type: string
|
||||
additionalProperties:
|
||||
description: Keys dependent on the login type
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
example:
|
||||
type: "example.type.foo"
|
||||
session: "xxxxx"
|
||||
example_credential: "verypoorsharedsecret"
|
||||
@ -0,0 +1,62 @@
|
||||
# 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.
|
||||
title: Authentication response
|
||||
description: |-
|
||||
Used by servers to indicate that additional authentication information is required,
|
||||
type: object
|
||||
properties:
|
||||
flows:
|
||||
description: A list of the login flows supported by the server for this API.
|
||||
title: Flow information
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
stages:
|
||||
description: |-
|
||||
The login type of each of the stages required to complete this
|
||||
authentication flow
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: "example.type.foo"
|
||||
required:
|
||||
- stages
|
||||
params:
|
||||
type: object
|
||||
description: |-
|
||||
Contains any information that the client will need to know in order to
|
||||
use a given type of authentication. For each login type presented,
|
||||
that type may be present as a key in this dictionary. For example, the
|
||||
public part of an OAuth client ID could be given here.
|
||||
additionalProperties:
|
||||
type: object
|
||||
example:
|
||||
"example.type.baz": { "example_key": "foobar" }
|
||||
session:
|
||||
type: string
|
||||
description: |-
|
||||
This is a session identifier that the client must pass back to the home
|
||||
server, if one is provided, in subsequent attempts to authenticate in the
|
||||
same API call.
|
||||
example: "xxxxxxyz"
|
||||
completed:
|
||||
type: array
|
||||
description: |-
|
||||
A list of the stages the client has completed successfully
|
||||
items:
|
||||
type: string
|
||||
example: "example.type.foo"
|
||||
required:
|
||||
- flows
|
||||
@ -0,0 +1,44 @@
|
||||
# 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.
|
||||
|
||||
type: object
|
||||
description: A client device
|
||||
title: Device
|
||||
properties:
|
||||
device_id:
|
||||
type: string
|
||||
description: Identifier of this device.
|
||||
example: QBUAZIFURK
|
||||
display_name:
|
||||
type: string
|
||||
description: |-
|
||||
Display name set by the user for this device. Absent if no name has been
|
||||
set.
|
||||
example: android
|
||||
last_seen_ip:
|
||||
type: string
|
||||
description: |-
|
||||
The IP address where this device was last seen. (May be a few minutes out
|
||||
of date, for efficiency reasons).
|
||||
example: 1.2.3.4
|
||||
last_seen_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The timestamp (in milliseconds since the unix epoch) when this devices
|
||||
was last seen. (May be a few minutes out of date, for efficiency
|
||||
reasons).
|
||||
example: 1474491775024
|
||||
required:
|
||||
- device_id
|
||||
@ -0,0 +1,55 @@
|
||||
# Copyright 2020 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.
|
||||
type: object
|
||||
title: CrossSigningKey
|
||||
description: Cross signing key
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the user the key belongs to.
|
||||
example: "@alice:example.com"
|
||||
usage:
|
||||
type: array
|
||||
description: |-
|
||||
What the key is used for.
|
||||
items:
|
||||
type: string
|
||||
enum: ["master", "self_signing", "user_signing"]
|
||||
keys:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |-
|
||||
The public key. The object must have exactly one property, whose name is
|
||||
in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value
|
||||
is the unpadded base64 public key.
|
||||
example:
|
||||
"ed25519:alice+base64+public+key": "alice+base64+public+key"
|
||||
signatures:
|
||||
type: object
|
||||
title: Signatures
|
||||
description: |-
|
||||
Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
|
||||
Optional for the master key. Other keys must be signed by the
|
||||
user\'s master key.
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"ed25519:alice+base64+master+key": "signature+of+key"
|
||||
}
|
||||
}
|
||||
required:
|
||||
- user_id
|
||||
- usage
|
||||
- keys
|
||||
@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
type: object
|
||||
title: DeviceKeys
|
||||
description: Device identity keys
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the user the device belongs to. Must match the user ID used
|
||||
when logging in.
|
||||
example: "@alice:example.com"
|
||||
device_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the device these keys belong to. Must match the device ID used
|
||||
when logging in.
|
||||
example: "JLAFKJWSCS"
|
||||
algorithms:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |-
|
||||
The encryption algorithms supported by this device.
|
||||
example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"]
|
||||
keys:
|
||||
type: object
|
||||
description: |-
|
||||
Public identity keys. The names of the properties should be in the
|
||||
format `<algorithm>:<device_id>`. The keys themselves should be
|
||||
encoded as specified by the key algorithm.
|
||||
additionalProperties:
|
||||
type: string
|
||||
example:
|
||||
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI"
|
||||
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
|
||||
signatures:
|
||||
type: object
|
||||
title: Signatures
|
||||
description: |-
|
||||
Signatures for the device key object. A map from user ID, to a map from
|
||||
`<algorithm>:<device_id>` to the signature.
|
||||
|
||||
The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
example:
|
||||
"@alice:example.com":
|
||||
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
|
||||
required:
|
||||
- user_id
|
||||
- device_id
|
||||
- algorithms
|
||||
- keys
|
||||
- signatures
|
||||
@ -0,0 +1,25 @@
|
||||
# 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.
|
||||
type: object
|
||||
description: A Matrix-level Error
|
||||
properties:
|
||||
errcode:
|
||||
type: string
|
||||
description: An error code.
|
||||
example: M_UNKNOWN
|
||||
error:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
example: An unknown error occurred
|
||||
required: ["errcode"]
|
||||
@ -0,0 +1,32 @@
|
||||
# Copyright 2018 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.
|
||||
$ref: error.yaml
|
||||
type: object
|
||||
description: The rate limit was reached for this request
|
||||
properties:
|
||||
errcode:
|
||||
type: string
|
||||
description: The M_LIMIT_EXCEEDED error code
|
||||
example: M_LIMIT_EXCEEDED
|
||||
error:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
example: Too many requests
|
||||
retry_after_ms:
|
||||
type: integer
|
||||
description: |-
|
||||
The amount of time in milliseconds the client should wait
|
||||
before trying the request again.
|
||||
example: 2000
|
||||
required: ["errcode"]
|
||||
@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
properties:
|
||||
event_id:
|
||||
description: The ID of this event, if applicable.
|
||||
type: string
|
||||
content:
|
||||
description: The content of this event. The fields in this object will vary depending
|
||||
on the type of event.
|
||||
title: EventContent
|
||||
type: object
|
||||
origin_server_ts:
|
||||
description: Timestamp in milliseconds on originating homeserver when this event
|
||||
was sent.
|
||||
format: int64
|
||||
type: integer
|
||||
sender:
|
||||
description: The MXID of the user who sent this event.
|
||||
type: string
|
||||
state_key:
|
||||
description: Optional. This key will only be present for state events. A unique
|
||||
key which defines the overwriting semantics for this piece of room state.
|
||||
type: string
|
||||
type:
|
||||
description: The type of event.
|
||||
type: string
|
||||
unsigned:
|
||||
description: Information about this event which was not sent by the originating
|
||||
homeserver
|
||||
properties:
|
||||
age:
|
||||
description: Time in milliseconds since the event was sent.
|
||||
format: int64
|
||||
type: integer
|
||||
prev_content:
|
||||
description: Optional. The previous `content` for this state. This will
|
||||
be present only for state events appearing in the `timeline`. If this
|
||||
is not a state event, or there is no previous content, this key will be
|
||||
missing.
|
||||
title: EventContent
|
||||
type: object
|
||||
transaction_id:
|
||||
description: Optional. The transaction ID set when this message was sent.
|
||||
This key will only be present for message events sent by the device calling
|
||||
this API.
|
||||
type: string
|
||||
redacted_because:
|
||||
description: Optional. The event that redacted this event, if any.
|
||||
title: Event
|
||||
type: object
|
||||
title: UnsignedData
|
||||
type: object
|
||||
title: Event
|
||||
type: object
|
||||
@ -0,0 +1,23 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
properties:
|
||||
events:
|
||||
description: List of events.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
|
||||
type: object
|
||||
type: array
|
||||
type: object
|
||||
@ -0,0 +1,47 @@
|
||||
# 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.
|
||||
title: EventFilter
|
||||
properties:
|
||||
limit:
|
||||
description: The maximum number of events to return.
|
||||
type: integer
|
||||
not_senders:
|
||||
description: A list of sender IDs to exclude. If this list is absent then no senders
|
||||
are excluded. A matching sender will be excluded even if it is listed in the
|
||||
`'senders'` filter.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
not_types:
|
||||
description: A list of event types to exclude. If this list is absent then no
|
||||
event types are excluded. A matching type will be excluded even if it is listed
|
||||
in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
|
||||
of characters.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
senders:
|
||||
description: A list of senders IDs to include. If this list is absent then all
|
||||
senders are included.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
types:
|
||||
description: A list of event types to include. If this list is absent then all
|
||||
event types are included. A `'*'` can be used as a wildcard to match any sequence
|
||||
of characters.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
type: object
|
||||
@ -0,0 +1,50 @@
|
||||
# Copyright 2019 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.
|
||||
|
||||
type: object
|
||||
title: KeyBackupData
|
||||
description: "The key data"
|
||||
properties:
|
||||
first_message_index:
|
||||
description: |-
|
||||
The index of the first message in the session that the key can decrypt.
|
||||
type: integer
|
||||
example: 1
|
||||
forwarded_count:
|
||||
description: |-
|
||||
The number of times this key has been forwarded via key-sharing between devices.
|
||||
type: integer
|
||||
example: 0
|
||||
is_verified:
|
||||
description: |-
|
||||
Whether the device backing up the key verified the device that the key
|
||||
is from.
|
||||
type: boolean
|
||||
example: false
|
||||
session_data:
|
||||
description: |-
|
||||
Algorithm-dependent data. See the documentation for the backup
|
||||
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
||||
expected format of the data.
|
||||
type: object
|
||||
example: {
|
||||
"ephemeral": "base64+ephemeral+key",
|
||||
"ciphertext": "base64+ciphertext+of+JSON+data",
|
||||
"mac": "base64+mac+of+ciphertext"
|
||||
}
|
||||
required:
|
||||
- first_message_index
|
||||
- forwarded_count
|
||||
- is_verified
|
||||
- session_data
|
||||
@ -0,0 +1,36 @@
|
||||
# Copyright 2018 New Vector Ltd
|
||||
# Copyright 2019 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.
|
||||
type: object
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token the consumer may use to verify the identity of
|
||||
the person who generated the token. This is given to the federation
|
||||
API `GET /openid/userinfo` to verify the user's identity.
|
||||
token_type:
|
||||
type: string
|
||||
description: The string `Bearer`.
|
||||
matrix_server_name:
|
||||
type: string
|
||||
description: |-
|
||||
The homeserver domain the consumer should use when attempting to
|
||||
verify the user's identity.
|
||||
expires_in:
|
||||
type: integer
|
||||
description: |-
|
||||
The number of seconds before this token expires and a new one must
|
||||
be generated.
|
||||
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
|
||||
@ -0,0 +1,105 @@
|
||||
# Copyright 2018 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.
|
||||
|
||||
type: object
|
||||
description: A list of the rooms on the server.
|
||||
required: ["chunk"]
|
||||
properties:
|
||||
chunk:
|
||||
title: "PublicRoomsChunks"
|
||||
type: array
|
||||
description: |-
|
||||
A paginated chunk of public rooms.
|
||||
items:
|
||||
type: object
|
||||
title: "PublicRoomsChunk"
|
||||
required:
|
||||
- room_id
|
||||
- num_joined_members
|
||||
- world_readable
|
||||
- guest_can_join
|
||||
properties:
|
||||
aliases:
|
||||
type: array
|
||||
description: |-
|
||||
Aliases of the room. May be empty.
|
||||
items:
|
||||
type: string
|
||||
canonical_alias:
|
||||
type: string
|
||||
description: |-
|
||||
The canonical alias of the room, if any.
|
||||
name:
|
||||
type: string
|
||||
description: |-
|
||||
The name of the room, if any.
|
||||
num_joined_members:
|
||||
type: integer
|
||||
description: |-
|
||||
The number of members joined to the room.
|
||||
room_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the room.
|
||||
topic:
|
||||
type: string
|
||||
description: |-
|
||||
The topic of the room, if any.
|
||||
world_readable:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the room may be viewed by guest users without joining.
|
||||
guest_can_join:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether guest users may join the room and participate in it.
|
||||
If they can, they will be subject to ordinary power level
|
||||
rules like any other user.
|
||||
avatar_url:
|
||||
type: string
|
||||
description: The URL for the room's avatar, if one is set.
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
A pagination token for the response. The absence of this token
|
||||
means there are no more results to fetch and the client should
|
||||
stop paginating.
|
||||
prev_batch:
|
||||
type: string
|
||||
description: |-
|
||||
A pagination token that allows fetching previous results. The
|
||||
absence of this token means there are no results before this
|
||||
batch, i.e. this is the first batch.
|
||||
total_room_count_estimate:
|
||||
type: integer
|
||||
description: |-
|
||||
An estimate on the total number of public rooms, if the
|
||||
server has an estimate.
|
||||
example: {
|
||||
"chunk": [
|
||||
{
|
||||
"aliases": ["#murrays:cheese.bar"],
|
||||
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
|
||||
"guest_can_join": false,
|
||||
"name": "CHEESE",
|
||||
"num_joined_members": 37,
|
||||
"room_id": "!ol19s:bleecker.street",
|
||||
"topic": "Tasty tasty cheese",
|
||||
"world_readable": true
|
||||
}
|
||||
],
|
||||
"next_batch": "p190q",
|
||||
"prev_batch": "p1902",
|
||||
"total_room_count_estimate": 115
|
||||
}
|
||||
@ -0,0 +1,49 @@
|
||||
# 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.
|
||||
|
||||
title: PushCondition
|
||||
type: object
|
||||
properties:
|
||||
kind:
|
||||
type: string
|
||||
description: |-
|
||||
The kind of condition to apply. See [conditions](/client-server-api/#conditions) for
|
||||
more information on the allowed kinds and how they work.
|
||||
key:
|
||||
type: string
|
||||
description: |-
|
||||
Required for `event_match` conditions. The dot-separated field of the
|
||||
event to match.
|
||||
|
||||
Required for `sender_notification_permission` conditions. The field in
|
||||
the power level event the user needs a minimum power level for. Fields
|
||||
must be specified under the `notifications` property in the power level
|
||||
event's `content`.
|
||||
x-example: content.body
|
||||
pattern:
|
||||
type: string
|
||||
description: |-
|
||||
Required for `event_match` conditions. The glob-style pattern to
|
||||
match against. Patterns with no special glob characters should be
|
||||
treated as having asterisks prepended and appended when testing the
|
||||
condition.
|
||||
is:
|
||||
type: string
|
||||
description: |-
|
||||
Required for `room_member_count` conditions. A decimal integer
|
||||
optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches
|
||||
rooms where the member count is strictly less than the given number and
|
||||
so forth. If no prefix is present, this parameter defaults to ==.
|
||||
required:
|
||||
- kind
|
||||
@ -0,0 +1,56 @@
|
||||
# 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.
|
||||
|
||||
title: PushRule
|
||||
type: object
|
||||
properties:
|
||||
actions:
|
||||
items:
|
||||
type:
|
||||
- object
|
||||
- string
|
||||
type: array
|
||||
description: |-
|
||||
The actions to perform when this rule is matched.
|
||||
default:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether this is a default rule, or has been set explicitly.
|
||||
enabled:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the push rule is enabled or not.
|
||||
rule_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of this rule.
|
||||
conditions:
|
||||
type: array
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_condition.yaml
|
||||
description: |-
|
||||
The conditions that must hold true for an event in order for a rule to be
|
||||
applied to an event. A rule with no conditions always matches. Only
|
||||
applicable to `underride` and `override` rules.
|
||||
pattern:
|
||||
type: string
|
||||
description: |-
|
||||
The glob-style pattern to match against. Only applicable to `content`
|
||||
rules.
|
||||
required:
|
||||
- actions
|
||||
- default
|
||||
- enabled
|
||||
- rule_id
|
||||
@ -0,0 +1,50 @@
|
||||
# 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.
|
||||
properties:
|
||||
content:
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_rule.yaml
|
||||
title: PushRule
|
||||
type: object
|
||||
type: array
|
||||
override:
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_rule.yaml
|
||||
title: PushRule
|
||||
type: object
|
||||
type: array
|
||||
room:
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_rule.yaml
|
||||
title: PushRule
|
||||
type: object
|
||||
type: array
|
||||
sender:
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_rule.yaml
|
||||
title: PushRule
|
||||
type: object
|
||||
type: array
|
||||
underride:
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_rule.yaml
|
||||
title: PushRule
|
||||
type: object
|
||||
type: array
|
||||
type: object
|
||||
@ -0,0 +1,36 @@
|
||||
# Copyright 2019 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.
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "../../identity/definitions/request_email_validation.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The hostname of the identity server to communicate with. May optionally
|
||||
include a port. This parameter is ignored when the homeserver handles
|
||||
3PID verification.
|
||||
|
||||
This parameter is deprecated with a plan to be removed in a future specification
|
||||
version for `/account/password` and `/register` requests.
|
||||
example: "id.example.com"
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
|
||||
Required if an `id_server` is supplied.
|
||||
@ -0,0 +1,36 @@
|
||||
# Copyright 2019 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.
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "../../identity/definitions/request_msisdn_validation.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The hostname of the identity server to communicate with. May optionally
|
||||
include a port. This parameter is ignored when the homeserver handles
|
||||
3PID verification.
|
||||
|
||||
This parameter is deprecated with a plan to be removed in a future specification
|
||||
version for `/account/password` and `/register` requests.
|
||||
example: "id.example.com"
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
|
||||
Required if an `id_server` is supplied.
|
||||
@ -0,0 +1,37 @@
|
||||
# Copyright 2019 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.
|
||||
type: object
|
||||
properties:
|
||||
sid:
|
||||
type: string
|
||||
description: |-
|
||||
The session ID. Session IDs are opaque strings that must consist entirely
|
||||
of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255
|
||||
characters and they must not be empty.
|
||||
example: "123abc"
|
||||
submit_url:
|
||||
type: string
|
||||
description: |-
|
||||
An optional field containing a URL where the client must submit the
|
||||
validation token to, with identical parameters to the Identity Service
|
||||
API's `POST /validate/email/submitToken` endpoint (without the requirement
|
||||
for an access token). The homeserver must send this token to the user (if
|
||||
applicable), who should then be prompted to provide it to the client.
|
||||
|
||||
If this field is not present, the client can assume that verification
|
||||
will happen without the client's involvement provided the homeserver
|
||||
advertises this specification version in the `/versions` response
|
||||
(ie: r0.5.0).
|
||||
example: "https://example.org/path/to/submitToken"
|
||||
required: ['sid']
|
||||
@ -0,0 +1,27 @@
|
||||
# Copyright 2018 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.
|
||||
properties:
|
||||
events:
|
||||
description: List of events.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: ../../../event-schemas/schema/core-event-schema/sync_room_event.yaml
|
||||
type: object
|
||||
required:
|
||||
- event_id
|
||||
#- room_id - Not in /sync
|
||||
- sender
|
||||
- origin_server_ts
|
||||
type: array
|
||||
type: object
|
||||
@ -0,0 +1,49 @@
|
||||
# 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.
|
||||
allOf:
|
||||
- $ref: event_filter.yaml
|
||||
- type: object
|
||||
title: RoomEventFilter
|
||||
properties:
|
||||
lazy_load_members:
|
||||
type: boolean
|
||||
description: |-
|
||||
If `true`, enables lazy-loading of membership events. See
|
||||
[Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
|
||||
for more information. Defaults to `false`.
|
||||
include_redundant_members:
|
||||
type: boolean
|
||||
description: |-
|
||||
If `true`, sends all membership events for all events, even if they have already
|
||||
been sent to the client. Does not
|
||||
apply unless `lazy_load_members` is `true`. See
|
||||
[Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
|
||||
for more information. Defaults to `false`.
|
||||
not_rooms:
|
||||
description: A list of room IDs to exclude. If this list is absent then no rooms
|
||||
are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
|
||||
filter.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
rooms:
|
||||
description: A list of room IDs to include. If this list is absent then all rooms
|
||||
are included.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
contains_url:
|
||||
type: boolean
|
||||
description: If `true`, includes only events with a `url` key in their content. If
|
||||
`false`, excludes those events. If omitted, `url` key is not considered for filtering.
|
||||
@ -0,0 +1,38 @@
|
||||
# Copyright 2020 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.
|
||||
|
||||
type: object
|
||||
title: RoomKeyBackup
|
||||
description: "The backed up keys for a room."
|
||||
properties:
|
||||
sessions:
|
||||
type: object
|
||||
description: "A map of session IDs to key data."
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: "key_backup_data.yaml"
|
||||
example: {
|
||||
"sessionid1": {
|
||||
"first_message_index": 1,
|
||||
"forwarded_count": 0,
|
||||
"is_verified": true,
|
||||
"session_data": {
|
||||
"ephemeral": "base64+ephemeral+key",
|
||||
"ciphertext": "base64+ciphertext+of+JSON+data",
|
||||
"mac": "base64+mac+of+ciphertext"
|
||||
}
|
||||
}
|
||||
}
|
||||
required:
|
||||
- sessions
|
||||
@ -0,0 +1,18 @@
|
||||
# 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.
|
||||
accessToken:
|
||||
type: apiKey
|
||||
description: The access_token returned by a call to `/login` or `/register`
|
||||
name: access_token
|
||||
in: query
|
||||
@ -0,0 +1,28 @@
|
||||
# Copyright 2018 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.
|
||||
properties:
|
||||
events:
|
||||
description: List of events.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: ../../../event-schemas/schema/core-event-schema/sync_state_event.yaml
|
||||
type: object
|
||||
required:
|
||||
- event_id
|
||||
#- room_id - Not in /sync
|
||||
- sender
|
||||
- origin_server_ts
|
||||
- state_key
|
||||
type: array
|
||||
type: object
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
type: object
|
||||
title: Filter
|
||||
properties:
|
||||
event_fields:
|
||||
description: List of event fields to include. If this list is absent then all
|
||||
fields are included. The entries may include '.' characters to indicate sub-fields.
|
||||
So ['content.body'] will include the 'body' field of the 'content' object. A
|
||||
literal '.' character in a field name may be escaped using a '\\'. A server may
|
||||
include more fields than were requested.
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
event_format:
|
||||
description: The format to use for events. 'client' will return the events in
|
||||
a format suitable for clients. 'federation' will return the raw event as received
|
||||
over federation. The default is 'client'.
|
||||
enum:
|
||||
- client
|
||||
- federation
|
||||
type: string
|
||||
presence:
|
||||
allOf:
|
||||
- $ref: event_filter.yaml
|
||||
description: The presence updates to include.
|
||||
account_data:
|
||||
allOf:
|
||||
- $ref: event_filter.yaml
|
||||
description: The user account data that isn't associated with rooms to include.
|
||||
room:
|
||||
title: RoomFilter
|
||||
description: Filters to be applied to room data.
|
||||
type: object
|
||||
properties:
|
||||
not_rooms:
|
||||
description: A list of room IDs to exclude. If this list is absent then no rooms
|
||||
are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
|
||||
filter. This filter is applied before the filters in `ephemeral`,
|
||||
`state`, `timeline` or `account_data`
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
rooms:
|
||||
description: A list of room IDs to include. If this list is absent then all rooms
|
||||
are included. This filter is applied before the filters in `ephemeral`,
|
||||
`state`, `timeline` or `account_data`
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
ephemeral:
|
||||
allOf:
|
||||
- $ref: room_event_filter.yaml
|
||||
description: The events that aren't recorded in the room history, e.g. typing
|
||||
and receipts, to include for rooms.
|
||||
include_leave:
|
||||
description: Include rooms that the user has left in the sync, default false
|
||||
type: boolean
|
||||
state:
|
||||
type: object
|
||||
title: StateFilter
|
||||
allOf:
|
||||
- $ref: room_event_filter.yaml
|
||||
description: The state events to include for rooms.
|
||||
timeline:
|
||||
allOf:
|
||||
- $ref: room_event_filter.yaml
|
||||
description: The message and state update events to include for rooms.
|
||||
account_data:
|
||||
allOf:
|
||||
- $ref: room_event_filter.yaml
|
||||
description: The per user account data to include for rooms.
|
||||
@ -0,0 +1,45 @@
|
||||
# Copyright 2019 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.
|
||||
type: object
|
||||
title: Third Party Signed
|
||||
description: |-
|
||||
A signature of an `m.third_party_invite` token to prove that this user
|
||||
owns a third party identity which has been invited to the room.
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
description: The Matrix ID of the user who issued the invite.
|
||||
example: "@alice:example.org"
|
||||
mxid:
|
||||
type: string
|
||||
description: The Matrix ID of the invitee.
|
||||
example: "@bob:example.org"
|
||||
token:
|
||||
type: string
|
||||
description: The state key of the m.third_party_invite event.
|
||||
example: "random8nonce"
|
||||
signatures:
|
||||
type: object
|
||||
description: A signatures object containing a signature of the entire signed object.
|
||||
title: Signatures
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
example: {
|
||||
"example.org": {
|
||||
"ed25519:0": "some9signature"
|
||||
}
|
||||
}
|
||||
required: ["sender", "mxid", "token", "signatures"]
|
||||
@ -0,0 +1,26 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 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.
|
||||
allOf:
|
||||
- $ref: room_event_batch.yaml
|
||||
properties:
|
||||
limited:
|
||||
description: True if the number of events returned was limited by the `limit`
|
||||
on the filter.
|
||||
type: boolean
|
||||
prev_batch:
|
||||
description: A token that can be supplied to the `from` parameter of the
|
||||
rooms/{roomId}/messages endpoint.
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,24 @@
|
||||
# Copyright 2018 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.
|
||||
title: User identifier
|
||||
description: |-
|
||||
Identification information for a user
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: The type of identification. See [Identifier types](/client-server-api/#identifier-types) for supported values and additional property descriptions.
|
||||
required:
|
||||
- type
|
||||
additionalProperties: true
|
||||
@ -0,0 +1,39 @@
|
||||
# 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.
|
||||
title: Discovery Information
|
||||
description: |-
|
||||
Used by clients to determine the homeserver, identity server, and other
|
||||
optional components they should be interacting with.
|
||||
type: object
|
||||
properties:
|
||||
"m.homeserver":
|
||||
$ref: "homeserver.yaml"
|
||||
"m.identity_server":
|
||||
$ref: "identity_server.yaml"
|
||||
additionalProperties:
|
||||
type: object
|
||||
description: Application-dependent keys using Java package naming convention.
|
||||
required:
|
||||
- m.homeserver
|
||||
example: {
|
||||
"m.homeserver": {
|
||||
"base_url": "https://matrix.example.com"
|
||||
},
|
||||
"m.identity_server": {
|
||||
"base_url": "https://identity.example.com"
|
||||
},
|
||||
"org.example.custom.property": {
|
||||
"app_url": "https://custom.app.example.org"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,24 @@
|
||||
# Copyright 2018 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.
|
||||
title: Homeserver Information
|
||||
description: |-
|
||||
Used by clients to discover homeserver information.
|
||||
type: object
|
||||
properties:
|
||||
base_url:
|
||||
type: string
|
||||
description: The base URL for the homeserver for client-server connections.
|
||||
example: https://matrix.example.com
|
||||
required:
|
||||
- base_url
|
||||
@ -0,0 +1,24 @@
|
||||
# Copyright 2018 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.
|
||||
title: Identity Server Information
|
||||
description: |-
|
||||
Used by clients to discover identity server information.
|
||||
type: object
|
||||
properties:
|
||||
base_url:
|
||||
type: string
|
||||
description: The base URL for the identity server for client-server connections.
|
||||
example: https://identity.example.com
|
||||
required:
|
||||
- base_url
|
||||
@ -0,0 +1,230 @@
|
||||
# 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 device management 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:
|
||||
"/devices":
|
||||
get:
|
||||
summary: List registered devices for the current user
|
||||
description: |-
|
||||
Gets information about all devices for the current user.
|
||||
operationId: getDevices
|
||||
security:
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: Device information
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
devices:
|
||||
type: array
|
||||
description: A list of all registered devices for this user.
|
||||
items:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "definitions/client_device.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"devices": [
|
||||
{
|
||||
"device_id": "QBUAZIFURK",
|
||||
"display_name": "android",
|
||||
"last_seen_ip": "1.2.3.4",
|
||||
"last_seen_ts": 1474491775024
|
||||
}
|
||||
]
|
||||
}
|
||||
tags:
|
||||
- Device management
|
||||
"/devices/{deviceId}":
|
||||
get:
|
||||
summary: Get a single device
|
||||
description: |-
|
||||
Gets information on a single device, by device id.
|
||||
operationId: getDevice
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: deviceId
|
||||
description: The device to retrieve.
|
||||
required: true
|
||||
x-example: "QBUAZIFURK"
|
||||
responses:
|
||||
200:
|
||||
description: Device information
|
||||
schema:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "definitions/client_device.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"device_id": "QBUAZIFURK",
|
||||
"display_name": "android",
|
||||
"last_seen_ip": "1.2.3.4",
|
||||
"last_seen_ts": 1474491775024
|
||||
}
|
||||
404:
|
||||
description: The current user has no device with the given ID.
|
||||
tags:
|
||||
- Device management
|
||||
put:
|
||||
summary: Update a device
|
||||
description: |-
|
||||
Updates the metadata on the given device.
|
||||
operationId: updateDevice
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: deviceId
|
||||
description: The device to update.
|
||||
required: true
|
||||
x-example: "QBUAZIFURK"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
description: New information for the device.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
display_name:
|
||||
type: string
|
||||
description: |-
|
||||
The new display name for this device. If not given, the
|
||||
display name is unchanged.
|
||||
example: { "display_name": "My other phone" }
|
||||
responses:
|
||||
200:
|
||||
description: The device was successfully updated.
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
schema:
|
||||
type: object # empty json object
|
||||
404:
|
||||
description: The current user has no device with the given ID.
|
||||
tags:
|
||||
- Device management
|
||||
delete:
|
||||
summary: Delete a device
|
||||
description: |-
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
Deletes the given device, and invalidates any access token associated with it.
|
||||
operationId: deleteDevice
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: deviceId
|
||||
description: The device to delete.
|
||||
required: true
|
||||
x-example: "QBUAZIFURK"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: |-
|
||||
Additional authentication information for the
|
||||
user-interactive authentication API.
|
||||
allOf:
|
||||
- "$ref": "definitions/auth_data.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The device was successfully removed, or had been removed
|
||||
previously.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
tags:
|
||||
- Device management
|
||||
"/delete_devices":
|
||||
post:
|
||||
summary: Bulk deletion of devices
|
||||
description: |-
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
Deletes the given devices, and invalidates any access token associated with them.
|
||||
operationId: deleteDevices
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
devices:
|
||||
type: array
|
||||
description: The list of device IDs to delete.
|
||||
items:
|
||||
type: string
|
||||
description: A list of device IDs.
|
||||
example: ["QBUAZIFURK", "AUIECTSRND"]
|
||||
auth:
|
||||
allOf:
|
||||
- "$ref": "definitions/auth_data.yaml"
|
||||
description: |-
|
||||
Additional authentication information for the
|
||||
user-interactive authentication API.
|
||||
required:
|
||||
- devices
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The devices were successfully removed, or had been removed
|
||||
previously.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
tags:
|
||||
- Device management
|
||||
@ -0,0 +1,237 @@
|
||||
# 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 Directory 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:
|
||||
"/directory/room/{roomAlias}":
|
||||
put:
|
||||
summary: Create a new mapping from room alias to room ID.
|
||||
operationId: setRoomAlias
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomAlias
|
||||
description: The room alias to set.
|
||||
required: true
|
||||
x-example: "#monkeys:matrix.org"
|
||||
- in: body
|
||||
name: body
|
||||
description: Information about this room alias.
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: The room ID to set.
|
||||
required: ['room_id']
|
||||
example: {
|
||||
"room_id": "!abnjk1jdasj98:capuchins.com"
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The mapping was created.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
409:
|
||||
description: A room alias with that name already exists.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_UNKNOWN",
|
||||
"error": "Room alias #monkeys:matrix.org already exists."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room directory
|
||||
get:
|
||||
summary: Get the room ID corresponding to this room alias.
|
||||
description: |-
|
||||
Requests that the server resolve a room alias to a room ID.
|
||||
|
||||
The server will use the federation API to resolve the alias if the
|
||||
domain part of the alias does not correspond to the server's own
|
||||
domain.
|
||||
|
||||
operationId: getRoomIdByAlias
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomAlias
|
||||
description: The room alias.
|
||||
required: true
|
||||
x-example: "#monkeys:matrix.org"
|
||||
responses:
|
||||
200:
|
||||
description: The room ID and other information for this alias.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: The room ID for this room alias.
|
||||
servers:
|
||||
type: array
|
||||
description: A list of servers that are aware of this room alias.
|
||||
items:
|
||||
type: string
|
||||
description: A server which is aware of this room alias.
|
||||
examples:
|
||||
application/json: {
|
||||
"room_id": "!abnjk1jdasj98:capuchins.com",
|
||||
"servers": [
|
||||
"capuchins.com",
|
||||
"matrix.org",
|
||||
"another.com"
|
||||
]
|
||||
}
|
||||
404:
|
||||
description: There is no mapped room ID for this room alias.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Room alias #monkeys:matrix.org not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room directory
|
||||
delete:
|
||||
summary: Remove a mapping of room alias to room ID.
|
||||
description: |-
|
||||
Remove a mapping of room alias to room ID.
|
||||
|
||||
Servers may choose to implement additional access control checks here, for instance that
|
||||
room aliases can only be deleted by their creator or a server administrator.
|
||||
|
||||
**Note:**
|
||||
Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias`
|
||||
state event in the room when an alias is removed. Servers which choose to update the
|
||||
canonical alias event are recommended to, in addition to their other relevant permission
|
||||
checks, delete the alias and return a successful response even if the user does not
|
||||
have permission to update the `m.room.canonical_alias` event.
|
||||
|
||||
operationId: deleteRoomAlias
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomAlias
|
||||
description: The room alias to remove.
|
||||
required: true
|
||||
x-example: "#monkeys:matrix.org"
|
||||
responses:
|
||||
200:
|
||||
description: The mapping was deleted.
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
404:
|
||||
description: There is no mapped room ID for this room alias.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Room alias #monkeys:example.org not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Room directory
|
||||
"/rooms/{roomId}/aliases":
|
||||
get:
|
||||
summary: Get a list of local aliases on a given room.
|
||||
description: |-
|
||||
Get a list of aliases maintained by the local server for the
|
||||
given room.
|
||||
|
||||
This endpoint can be called by users who are in the room (external
|
||||
users receive an `M_FORBIDDEN` error response). If the room's
|
||||
`m.room.history_visibility` maps to `world_readable`, any
|
||||
user can call this endpoint.
|
||||
|
||||
Servers may choose to implement additional access control checks here,
|
||||
such as allowing server administrators to view aliases regardless of
|
||||
membership.
|
||||
|
||||
**Note:**
|
||||
Clients are recommended not to display this list of aliases prominently
|
||||
as they are not curated, unlike those listed in the `m.room.canonical_alias`
|
||||
state event.
|
||||
|
||||
operationId: getLocalAliases
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room ID to find local aliases of.
|
||||
required: true
|
||||
x-example: "!abc123:example.org"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The list of local aliases for the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"aliases": [
|
||||
"#somewhere:example.com",
|
||||
"#another:example.com",
|
||||
"#hat_trick:example.com"
|
||||
]
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
aliases:
|
||||
type: array
|
||||
description: The server's local aliases on the room. Can be empty.
|
||||
items:
|
||||
type: string
|
||||
required: ['aliases']
|
||||
403:
|
||||
description: The user is not permitted to retrieve the list of local aliases for the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You are not a member of the room."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Room directory
|
||||
@ -0,0 +1,150 @@
|
||||
# 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 Event Context 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}/context/{eventId}":
|
||||
get:
|
||||
summary: Get events and state around the specified event.
|
||||
description: |-
|
||||
This API returns a number of events that happened just before and
|
||||
after the specified event. This allows clients to get the context
|
||||
surrounding an event.
|
||||
|
||||
*Note*: This endpoint supports lazy-loading of room member events. See
|
||||
[Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
|
||||
operationId: getEventContext
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room to get events from.
|
||||
required: true
|
||||
x-example: "!636q39766251:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventId
|
||||
description: The event to get context around.
|
||||
required: true
|
||||
x-example: "$f3h4d129462ha:example.com"
|
||||
- in: query
|
||||
type: integer
|
||||
name: limit
|
||||
description: |-
|
||||
The maximum number of events to return. Default: 10.
|
||||
x-example: 3
|
||||
- in: query
|
||||
name: filter
|
||||
type: string
|
||||
description: |-
|
||||
A JSON `RoomEventFilter` to filter the returned events with. The
|
||||
filter is only applied to `events_before`, `events_after`, and
|
||||
`state`. It is not applied to the `event` itself. The filter may
|
||||
be applied before or/and after the `limit` parameter - whichever the
|
||||
homeserver prefers.
|
||||
|
||||
See [Filtering](/client-server-api/#filtering) for more information.
|
||||
x-example: "66696p746572"
|
||||
responses:
|
||||
200:
|
||||
description: The events and state surrounding the requested event.
|
||||
schema:
|
||||
type: object
|
||||
description: The events and state surrounding the requested event.
|
||||
properties:
|
||||
start:
|
||||
type: string
|
||||
description: |-
|
||||
A token that can be used to paginate backwards with.
|
||||
end:
|
||||
type: string
|
||||
description: |-
|
||||
A token that can be used to paginate forwards with.
|
||||
events_before:
|
||||
type: array
|
||||
description: |-
|
||||
A list of room events that happened just before the
|
||||
requested event, in reverse-chronological order.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
|
||||
event:
|
||||
description: |-
|
||||
Details of the requested event.
|
||||
allOf:
|
||||
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
|
||||
events_after:
|
||||
type: array
|
||||
description: |-
|
||||
A list of room events that happened just after the
|
||||
requested event, in chronological order.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
|
||||
state:
|
||||
type: array
|
||||
description: |-
|
||||
The state of the room at the last event returned.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"end": "t29-57_2_0_2",
|
||||
"events_after": [
|
||||
{
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
|
||||
}
|
||||
],
|
||||
"event": {
|
||||
"event_id": "$f3h4d129462ha:example.com",
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.image.yaml"
|
||||
},
|
||||
"events_before": [
|
||||
{
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
|
||||
}
|
||||
],
|
||||
"start": "t27-54_2_0_2",
|
||||
"state": [
|
||||
{
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"$ref": "../../event-schemas/examples/m.room.create.yaml"
|
||||
},
|
||||
{
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
}
|
||||
]
|
||||
}
|
||||
tags:
|
||||
- Room participation
|
||||
@ -0,0 +1,156 @@
|
||||
# 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 filter API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/user/{userId}/filter":
|
||||
post:
|
||||
summary: Upload a new filter.
|
||||
description: |-
|
||||
Uploads a new filter definition to the homeserver.
|
||||
Returns a filter ID that may be used in future requests to
|
||||
restrict which events are returned to the client.
|
||||
operationId: defineFilter
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description:
|
||||
The id of the user uploading the filter. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
x-example: "@alice:example.com"
|
||||
- in: body
|
||||
name: filter
|
||||
required: true
|
||||
description: The filter to upload.
|
||||
schema:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "definitions/sync_filter.yaml"
|
||||
example: {
|
||||
"room": {
|
||||
"state": {
|
||||
"types": ["m.room.*"],
|
||||
"not_rooms": ["!726s6s6q:example.com"]
|
||||
},
|
||||
"timeline": {
|
||||
"limit": 10,
|
||||
"types": ["m.room.message"],
|
||||
"not_rooms": ["!726s6s6q:example.com"],
|
||||
"not_senders": ["@spam:example.com"]
|
||||
},
|
||||
"ephemeral": {
|
||||
"types": ["m.receipt", "m.typing"],
|
||||
"not_rooms": ["!726s6s6q:example.com"],
|
||||
"not_senders": ["@spam:example.com"]
|
||||
}
|
||||
},
|
||||
"presence": {
|
||||
"types": ["m.presence"],
|
||||
"not_senders": ["@alice:example.com"]
|
||||
},
|
||||
"event_format": "client",
|
||||
"event_fields": ["type", "content", "sender"]
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: The filter was created.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
filter_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the filter that was created. Cannot start
|
||||
with a `{` as this character is used to determine
|
||||
if the filter provided is inline JSON or a previously
|
||||
declared filter by homeservers on some APIs.
|
||||
example: "66696p746572"
|
||||
required: ['filter_id']
|
||||
tags:
|
||||
- Room participation
|
||||
"/user/{userId}/filter/{filterId}":
|
||||
get:
|
||||
summary: Download a filter
|
||||
operationId: getFilter
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
type: string
|
||||
description: |-
|
||||
The user ID to download a filter for.
|
||||
x-example: "@alice:example.com"
|
||||
required: true
|
||||
- in: path
|
||||
name: filterId
|
||||
type: string
|
||||
description: |-
|
||||
The filter ID to download.
|
||||
x-example: "66696p746572"
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The filter definition.
|
||||
examples:
|
||||
application/json: {
|
||||
"room": {
|
||||
"state": {
|
||||
"types": ["m.room.*"],
|
||||
"not_rooms": ["!726s6s6q:example.com"]
|
||||
},
|
||||
"timeline": {
|
||||
"limit": 10,
|
||||
"types": ["m.room.message"],
|
||||
"not_rooms": ["!726s6s6q:example.com"],
|
||||
"not_senders": ["@spam:example.com"]
|
||||
},
|
||||
"ephemeral": {
|
||||
"types": ["m.receipt", "m.typing"],
|
||||
"not_rooms": ["!726s6s6q:example.com"],
|
||||
"not_senders": ["@spam:example.com"]
|
||||
}
|
||||
},
|
||||
"presence": {
|
||||
"types": ["m.presence"],
|
||||
"not_senders": ["@alice:example.com"]
|
||||
},
|
||||
"event_format": "client",
|
||||
"event_fields": ["type", "content", "sender"]
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
allOf:
|
||||
- $ref: "definitions/sync_filter.yaml"
|
||||
404:
|
||||
description: "Unknown filter."
|
||||
tags:
|
||||
- Room participation
|
||||
@ -0,0 +1,120 @@
|
||||
# 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 Room Joining 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:
|
||||
# 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 ":
|
||||
post:
|
||||
summary: Invite a user to participate in a particular room.
|
||||
description: |-
|
||||
*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
|
||||
identifier of the invitee. The other is documented in the*
|
||||
[third party invites section](/client-server-api/#post_matrixclientr0roomsroomidinvite-1).
|
||||
|
||||
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.
|
||||
|
||||
If the user was invited to the room, the homeserver will append a
|
||||
`m.room.member` event to the room.
|
||||
|
||||
operationId: inviteUser
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room identifier (not alias) to which to invite the user.
|
||||
required: true
|
||||
x-example: "!d41d8cd:matrix.org"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"user_id": "@cheeky_monkey:matrix.org",
|
||||
"reason": "Welcome to the team!"
|
||||
}
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The fully qualified user ID of the invitee.
|
||||
reason:
|
||||
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.
|
||||
examples:
|
||||
application/json: {
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
400:
|
||||
description: |-
|
||||
|
||||
The request is invalid. A meaningful `errcode` and description
|
||||
error text will be returned. Example reasons for rejection include:
|
||||
|
||||
- The request body is malformed (`errcode` set to `M_BAD_JSON`
|
||||
or `M_NOT_JSON`).
|
||||
|
||||
- One or more users being invited to the room are residents of a
|
||||
homeserver which does not support the requested room version. The
|
||||
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
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:
|
||||
|
||||
- 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.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
@ -0,0 +1,193 @@
|
||||
# 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 Room Inviting 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}/join":
|
||||
post:
|
||||
summary: Start the requesting user participating in a particular room.
|
||||
description: |-
|
||||
*Note that this API requires a room ID, not alias.*
|
||||
`/join/{roomIdOrAlias}` *exists if you have a room alias.*
|
||||
|
||||
This API starts a user participating in a particular room, if that user
|
||||
is allowed to participate in that room. After this call, the client is
|
||||
allowed to see all current state events in the room, and all subsequent
|
||||
events associated with the room until the user leaves the room.
|
||||
|
||||
After a user has joined a room, the room will appear as an entry in the
|
||||
response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync)
|
||||
and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs.
|
||||
operationId: joinRoomById
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room identifier (not alias) to join.
|
||||
required: true
|
||||
x-example: "!d41d8cd:matrix.org"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
third_party_signed:
|
||||
allOf:
|
||||
- $ref: "definitions/third_party_signed.yaml"
|
||||
description: |-
|
||||
If supplied, the homeserver must verify that it matches a pending
|
||||
`m.room.third_party_invite` event in the room, and perform
|
||||
key validity checking if required by the event.
|
||||
reason:
|
||||
type: string
|
||||
description: |-
|
||||
Optional reason to be included as the `reason` on the subsequent
|
||||
membership event.
|
||||
example: "Looking for support"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The room has been joined.
|
||||
|
||||
The joined room ID must be returned in the `room_id` field.
|
||||
examples:
|
||||
application/json: {
|
||||
"room_id": "!d41d8cd:matrix.org"}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: The joined room ID.
|
||||
required: ["room_id"]
|
||||
403:
|
||||
description: |-
|
||||
You do not have permission to join the room. A meaningful `errcode`
|
||||
and description error text will be returned. Example reasons for rejection are:
|
||||
|
||||
- The room is invite-only and the user was not invited.
|
||||
- The user has been banned from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
"/join/{roomIdOrAlias}":
|
||||
post:
|
||||
summary: Start the requesting user participating in a particular room.
|
||||
description: |-
|
||||
*Note that this API takes either a room ID or alias, unlike* `/room/{roomId}/join`.
|
||||
|
||||
This API starts a user participating in a particular room, if that user
|
||||
is allowed to participate in that room. After this call, the client is
|
||||
allowed to see all current state events in the room, and all subsequent
|
||||
events associated with the room until the user leaves the room.
|
||||
|
||||
After a user has joined a room, the room will appear as an entry in the
|
||||
response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync)
|
||||
and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs.
|
||||
operationId: joinRoom
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomIdOrAlias
|
||||
description: The room identifier or alias to join.
|
||||
required: true
|
||||
x-example: "#monkeys:matrix.org"
|
||||
- in: query
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
name: server_name
|
||||
description: |-
|
||||
The servers to attempt to join the room through. One of the servers
|
||||
must be participating in the room.
|
||||
x-example: ["matrix.org", "elsewhere.ca"]
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
third_party_signed:
|
||||
allOf:
|
||||
- $ref: "definitions/third_party_signed.yaml"
|
||||
description: |-
|
||||
If a `third_party_signed` was supplied, the homeserver must verify
|
||||
that it matches a pending `m.room.third_party_invite` event in the
|
||||
room, and perform key validity checking if required by the event.
|
||||
reason:
|
||||
type: string
|
||||
description: |-
|
||||
Optional reason to be included as the `reason` on the subsequent
|
||||
membership event.
|
||||
example: "Looking for support"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The room has been joined.
|
||||
|
||||
The joined room ID must be returned in the `room_id` field.
|
||||
examples:
|
||||
application/json: {
|
||||
"room_id": "!d41d8cd:matrix.org"}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: The joined room ID.
|
||||
required: ["room_id"]
|
||||
403:
|
||||
description: |-
|
||||
You do not have permission to join the room. A meaningful `errcode`
|
||||
and description error text will be returned. Example reasons for rejection are:
|
||||
|
||||
- The room is invite-only and the user was not invited.
|
||||
- The user has been banned from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
@ -0,0 +1,925 @@
|
||||
# Copyright 2019-2020 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Key Backup 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:
|
||||
"/room_keys/version":
|
||||
post:
|
||||
summary: Create a new backup.
|
||||
description: |-
|
||||
Creates a new backup.
|
||||
operationId: postRoomKeysVersion
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: version
|
||||
description: "The backup configuration."
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
algorithm:
|
||||
description: The algorithm used for storing backups.
|
||||
type: string
|
||||
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
|
||||
example: "m.megolm_backup.v1.curve25519-aes-sha2"
|
||||
auth_data:
|
||||
description: |-
|
||||
Algorithm-dependent data. See the documentation for the backup
|
||||
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
||||
expected format of the data.
|
||||
type: object
|
||||
example: {
|
||||
"public_key": "abcdefg",
|
||||
"signatures": {
|
||||
"@alice:example.org": {
|
||||
"ed25519:deviceid": "signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
required:
|
||||
- algorithm
|
||||
- auth_data
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The version id of the new backup.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
version:
|
||||
type: string
|
||||
description: The backup version. This is an opaque string.
|
||||
example: "1"
|
||||
required:
|
||||
- version
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
get:
|
||||
summary: Get information about the latest backup version.
|
||||
description: |-
|
||||
Get information about the latest backup version.
|
||||
operationId: getRoomKeysVersionCurrent
|
||||
security:
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The information about the backup.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
algorithm:
|
||||
type: string
|
||||
description: The algorithm used for storing backups.
|
||||
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
|
||||
example: "m.megolm_backup.v1.curve25519-aes-sha2"
|
||||
auth_data:
|
||||
description: |-
|
||||
Algorithm-dependent data. See the documentation for the backup
|
||||
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
||||
expected format of the data.
|
||||
type: object
|
||||
example: {
|
||||
"public_key": "abcdefg",
|
||||
"signatures": {
|
||||
"@alice:example.org": {
|
||||
"ed25519:deviceid": "signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
count:
|
||||
description: The number of keys stored in the backup.
|
||||
type: integer
|
||||
example: 42
|
||||
etag:
|
||||
description: |-
|
||||
An opaque string representing stored keys in the backup.
|
||||
Clients can compare it with the `etag` value they received
|
||||
in the request of their last key storage request. If not
|
||||
equal, another client has modified the backup.
|
||||
type: string
|
||||
example: "anopaquestring"
|
||||
version:
|
||||
type: string
|
||||
description: The backup version.
|
||||
example: "1"
|
||||
required:
|
||||
- algorithm
|
||||
- auth_data
|
||||
- count
|
||||
- etag
|
||||
- version
|
||||
404:
|
||||
description:
|
||||
No backup exists.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "No current backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
"/room_keys/version/{version}":
|
||||
get:
|
||||
summary: Get information about an existing backup.
|
||||
description: |-
|
||||
Get information about an existing backup.
|
||||
operationId: getRoomKeysVersion
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup version to get, as returned in the `version` parameter
|
||||
of the response in
|
||||
[`POST /_matrix/client/r0/room_keys/version`](/client-server/#post_matrixclientr0room_keysversion)
|
||||
or this endpoint.
|
||||
required: true
|
||||
x-example: "1"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The information about the requested backup.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
algorithm:
|
||||
type: string
|
||||
description: The algorithm used for storing backups.
|
||||
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
|
||||
example: "m.megolm_backup.v1.curve25519-aes-sha2"
|
||||
auth_data:
|
||||
description: |-
|
||||
Algorithm-dependent data. See the documentation for the backup
|
||||
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
||||
expected format of the data.
|
||||
type: object
|
||||
example: {
|
||||
"public_key": "abcdefg",
|
||||
"signatures": {
|
||||
"@alice:example.org": {
|
||||
"ed25519:deviceid": "signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
count:
|
||||
description: The number of keys stored in the backup.
|
||||
type: integer
|
||||
example: 42
|
||||
etag:
|
||||
description: |-
|
||||
An opaque string representing stored keys in the backup.
|
||||
Clients can compare it with the `etag` value they received
|
||||
in the request of their last key storage request. If not
|
||||
equal, another client has modified the backup.
|
||||
type: string
|
||||
example: "anopaquestring"
|
||||
version:
|
||||
type: string
|
||||
description: The backup version.
|
||||
example: "1"
|
||||
required:
|
||||
- algorithm
|
||||
- auth_data
|
||||
- count
|
||||
- etag
|
||||
- version
|
||||
404:
|
||||
description:
|
||||
The backup specified does not exist.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
put:
|
||||
summary: Update information about an existing backup.
|
||||
description: |-
|
||||
Update information about an existing backup. Only `auth_data` can be modified.
|
||||
operationId: putRoomKeysVersion
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup version to update, as returned in the `version`
|
||||
parameter in the response of
|
||||
[`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion)
|
||||
or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion).
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: body
|
||||
name: version
|
||||
description: "The backup configuration"
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
algorithm:
|
||||
description: |-
|
||||
The algorithm used for storing backups. Must be the same as
|
||||
the algorithm currently used by the backup.
|
||||
type: string
|
||||
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
|
||||
example: "m.megolm_backup.v1.curve25519-aes-sha2"
|
||||
auth_data:
|
||||
description: |-
|
||||
Algorithm-dependent data. See the documentation for the backup
|
||||
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
||||
expected format of the data.
|
||||
type: object
|
||||
example: {
|
||||
"public_key": "abcdefg",
|
||||
"signatures": {
|
||||
"@alice:example.org": {
|
||||
"ed25519:deviceid": "signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
version:
|
||||
description: |-
|
||||
The backup version. If present, must be the same as the
|
||||
version in the path parameter.
|
||||
type: string
|
||||
example: "1"
|
||||
required:
|
||||
- algorithm
|
||||
- auth_data
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded.
|
||||
schema:
|
||||
type: object
|
||||
properties: {}
|
||||
400:
|
||||
description: |-
|
||||
A parameter was incorrect. For example, the `algorithm` does not
|
||||
match the current backup algorithm, or the `version` in the body
|
||||
does not match the `version` in the path.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "Algorithm does not match"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
404:
|
||||
description: The backup specified does not exist.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
delete:
|
||||
summary: Delete an existing key backup.
|
||||
description: |-
|
||||
Delete an existing key backup. Both the information about the backup,
|
||||
as well as all key data related to the backup will be deleted.
|
||||
operationId: deleteRoomKeysVersion
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup version to delete, as returned in the `version`
|
||||
parameter in the response of
|
||||
[`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion)
|
||||
or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion).
|
||||
required: true
|
||||
x-example: "1"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The delete succeeded, or the specified backup was previously
|
||||
deleted.
|
||||
schema:
|
||||
type: object
|
||||
properties: {}
|
||||
404:
|
||||
description: |-
|
||||
The backup specified does not exist. If the backup was previously
|
||||
deleted, the call should succeed rather than returning an error.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
"/room_keys/keys/{roomId}/{sessionId}":
|
||||
put:
|
||||
summary: Store a key in the backup.
|
||||
description: |-
|
||||
Store a key in the backup.
|
||||
operationId: postRoomKeysKeyRoomIdSessionId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup in which to store the key. Must be the current backup.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the key is for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: sessionId
|
||||
description: The ID of the megolm session that the key is for.
|
||||
required: true
|
||||
x-example: "sessionid"
|
||||
- in: body
|
||||
name: data
|
||||
description: "The key data."
|
||||
required: true
|
||||
schema:
|
||||
"$ref": "definitions/key_backup_data.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
403:
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
The current version will be included in the `current_version`
|
||||
field.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||
"error": "Wrong backup version.",
|
||||
"current_version": "42"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
get:
|
||||
summary: Retrieve a key from the backup
|
||||
description: |-
|
||||
Retrieve a key from the backup.
|
||||
operationId: getRoomKeysKeyRoomIdSessionId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to retrieve the key.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the requested key is for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: sessionId
|
||||
description: The ID of the megolm session whose key is requested.
|
||||
required: true
|
||||
x-example: "sessionid"
|
||||
responses:
|
||||
200:
|
||||
description: The key data
|
||||
schema:
|
||||
"$ref": "definitions/key_backup_data.yaml"
|
||||
404:
|
||||
description: The key or backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Key not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
delete:
|
||||
summary: Delete a key from the backup
|
||||
description: |-
|
||||
Delete a key from the backup.
|
||||
operationId: deleteRoomKeysKeyRoomIdSessionId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to delete the key
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the specified key is for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: sessionId
|
||||
description: The ID of the megolm session whose key is to be deleted.
|
||||
required: true
|
||||
x-example: "sessionid"
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
"/room_keys/keys/{roomId}":
|
||||
put:
|
||||
summary: Store several keys in the backup for a given room.
|
||||
description: |-
|
||||
Store a key in the backup.
|
||||
operationId: postRoomKeysKeyRoomId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup in which to store the keys. Must be the current backup.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the keys are for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
- in: body
|
||||
description: "The backup data"
|
||||
name: backupData
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/room_key_backup.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
403:
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
The current version will be included in the `current_version`
|
||||
field.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||
"error": "Wrong backup version.",
|
||||
"current_version": "42"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
get:
|
||||
summary: Retrieve the keys from the backup for a given room
|
||||
description: |-
|
||||
Retrieve the keys from the backup for a given room
|
||||
operationId: getRoomKeysKeyRoomId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to retrieve the key.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the requested key is for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The key data. If no keys are found, then an object with an empty
|
||||
`sessions` property will be returned (`{"sessions": {}}`).
|
||||
schema:
|
||||
type: object
|
||||
$ref: "definitions/room_key_backup.yaml"
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
delete:
|
||||
summary: Delete a key from the backup
|
||||
description: |-
|
||||
Delete a key from the backup.
|
||||
operationId: deleteRoomKeysKeyRoomId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to delete the key.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room that the specified key is for.
|
||||
required: true
|
||||
x-example: "!roomid:example.org"
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
"/room_keys/keys":
|
||||
put:
|
||||
summary: Store several keys in the backup.
|
||||
description: |-
|
||||
Store several keys in the backup.
|
||||
operationId: postRoomKeysKey
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup in which to store the keys. Must be the current backup.
|
||||
required: true
|
||||
x-example: "1"
|
||||
- in: body
|
||||
description: "The backup data."
|
||||
name: backupData
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
rooms:
|
||||
type: object
|
||||
description: |-
|
||||
A map of room IDs to room key backup data.
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: "definitions/room_key_backup.yaml"
|
||||
example: {
|
||||
"!room:example.org": {
|
||||
"sessions": {
|
||||
"sessionid1": {
|
||||
"first_message_index": 1,
|
||||
"forwarded_count": 0,
|
||||
"is_verified": true,
|
||||
"session_data": {
|
||||
"ephemeral": "base64+ephemeral+key",
|
||||
"ciphertext": "base64+ciphertext+of+JSON+data",
|
||||
"mac": "base64+mac+of+ciphertext"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
required:
|
||||
- rooms
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
403:
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
The current version will be included in the `current_version`
|
||||
field.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||
"error": "Wrong backup version.",
|
||||
"current_version": "42"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
get:
|
||||
summary: Retrieve the keys from the backup for a given room
|
||||
description: |-
|
||||
Retrieve the keys from the backup for a given room
|
||||
operationId: getRoomKeysKeyRoomId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to retrieve the keys.
|
||||
required: true
|
||||
x-example: "1"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The key data. If no keys are found, then an object with an empty
|
||||
`rooms` property will be returned (`{"rooms": {}}`).
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
rooms:
|
||||
type: object
|
||||
description: |-
|
||||
A map of room IDs to room key backup data.
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: "definitions/room_key_backup.yaml"
|
||||
example: {
|
||||
"!room:example.org": {
|
||||
"sessions": {
|
||||
"sessionid1": {
|
||||
"first_message_index": 1,
|
||||
"forwarded_count": 0,
|
||||
"is_verified": true,
|
||||
"session_data": {
|
||||
"ephemeral": "base64+ephemeral+key",
|
||||
"ciphertext": "base64+ciphertext+of+JSON+data",
|
||||
"mac": "base64+mac+of+ciphertext"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
404:
|
||||
description: The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
delete:
|
||||
summary: Delete a key from the backup
|
||||
description: |-
|
||||
Delete a key from the backup.
|
||||
operationId: deleteRoomKeysKeyRoomId
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: version
|
||||
description: |-
|
||||
The backup from which to delete the key
|
||||
required: true
|
||||
x-example: "1"
|
||||
responses:
|
||||
200:
|
||||
description: The update succeeded
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: "abcdefg"
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
404:
|
||||
description: |-
|
||||
The backup was not found.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown backup version"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
@ -0,0 +1,481 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2018 New Vector Ltd
|
||||
# Copyright 2020 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Client Config 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:
|
||||
"/keys/upload":
|
||||
post:
|
||||
summary: Upload end-to-end encryption keys.
|
||||
description: |-
|
||||
Publishes end-to-end encryption keys for the device.
|
||||
operationId: uploadKeys
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: keys
|
||||
description: |-
|
||||
The keys to be published
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
device_keys:
|
||||
description: |-
|
||||
Identity keys for the device. May be absent if no new
|
||||
identity keys are required.
|
||||
allOf:
|
||||
- $ref: definitions/device_keys.yaml
|
||||
one_time_keys:
|
||||
type: object
|
||||
description: |-
|
||||
One-time public keys for "pre-key" messages. The names of
|
||||
the properties should be in the format
|
||||
`<algorithm>:<key_id>`. The format of the key is determined
|
||||
by the [key algorithm](/client-server-api/#key-algorithms).
|
||||
|
||||
May be absent if no new one-time keys are required.
|
||||
additionalProperties:
|
||||
type:
|
||||
- string
|
||||
- object
|
||||
# XXX: We can't define an actual object here, so we have to hope
|
||||
# that people will look at the swagger source or can figure it out
|
||||
# from the other endpoints/example.
|
||||
# - type: object
|
||||
# title: KeyObject
|
||||
# properties:
|
||||
# key:
|
||||
# type: string
|
||||
# description: The key, encoded using unpadded base64.
|
||||
# signatures:
|
||||
# type: object
|
||||
# description: |-
|
||||
# Signature for the device. Mapped from user ID to signature object.
|
||||
# additionalProperties:
|
||||
# type: string
|
||||
# required: ['key', 'signatures']
|
||||
example: {
|
||||
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
|
||||
"signed_curve25519:AAAAHg": {
|
||||
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
|
||||
}
|
||||
}
|
||||
},
|
||||
"signed_curve25519:AAAAHQ": {
|
||||
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The provided keys were successfully uploaded.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
one_time_key_counts:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: integer
|
||||
description: |-
|
||||
For each key algorithm, the number of unclaimed one-time keys
|
||||
of that type currently held on the server for this device.
|
||||
example:
|
||||
curve25519: 10
|
||||
signed_curve25519: 20
|
||||
required:
|
||||
- one_time_key_counts
|
||||
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
"/keys/query":
|
||||
post:
|
||||
summary: Download device identity keys.
|
||||
description: |-
|
||||
Returns the current devices and identity keys for the given users.
|
||||
operationId: queryKeys
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: query
|
||||
description: |-
|
||||
Query defining the keys to be downloaded
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
timeout:
|
||||
type: integer
|
||||
description: |-
|
||||
The time (in milliseconds) to wait when downloading keys from
|
||||
remote servers. 10 seconds is the recommended default.
|
||||
example: 10000
|
||||
device_keys:
|
||||
type: object
|
||||
description: |-
|
||||
The keys to be downloaded. A map from user ID, to a list of
|
||||
device IDs, or to an empty list to indicate all devices for the
|
||||
corresponding user.
|
||||
additionalProperties:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: "device ID"
|
||||
example:
|
||||
"@alice:example.com": []
|
||||
token:
|
||||
type: string
|
||||
description: |-
|
||||
If the client is fetching keys as a result of a device update received
|
||||
in a sync request, this should be the 'since' token of that sync request,
|
||||
or any later sync token. This allows the server to ensure its response
|
||||
contains the keys advertised by the notification in that sync.
|
||||
required:
|
||||
- device_keys
|
||||
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The device information
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
failures:
|
||||
type: object
|
||||
description: |-
|
||||
If any remote homeservers could not be reached, they are
|
||||
recorded here. The names of the properties are the names of
|
||||
the unreachable servers.
|
||||
|
||||
If the homeserver could be reached, but the user or device
|
||||
was unknown, no failure is recorded. Instead, the corresponding
|
||||
user or device is missing from the `device_keys` result.
|
||||
additionalProperties:
|
||||
type: object
|
||||
example: {}
|
||||
device_keys:
|
||||
type: object
|
||||
description: |-
|
||||
Information on the queried devices. A map from user ID, to a
|
||||
map from device ID to device information. For each device,
|
||||
the information returned will be the same as uploaded via
|
||||
`/keys/upload`, with the addition of an `unsigned`
|
||||
property.
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
title: DeviceInformation
|
||||
allOf:
|
||||
- $ref: definitions/device_keys.yaml
|
||||
properties:
|
||||
unsigned:
|
||||
title: UnsignedDeviceInfo
|
||||
type: object
|
||||
description: |-
|
||||
Additional data added to the device key information
|
||||
by intermediate servers, and not covered by the
|
||||
signatures.
|
||||
properties:
|
||||
device_display_name:
|
||||
type: string
|
||||
description:
|
||||
The display name which the user set on the device.
|
||||
example:
|
||||
"@alice:example.com":
|
||||
JLAFKJWSCS: {
|
||||
"user_id": "@alice:example.com",
|
||||
"device_id": "JLAFKJWSCS",
|
||||
"algorithms": [
|
||||
"m.olm.v1.curve25519-aes-sha2",
|
||||
"m.megolm.v1.aes-sha2"
|
||||
],
|
||||
"keys": {
|
||||
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
|
||||
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
|
||||
}
|
||||
},
|
||||
"unsigned": {
|
||||
"device_display_name": "Alice's mobile phone"
|
||||
}
|
||||
}
|
||||
master_keys:
|
||||
type: object
|
||||
description: |-
|
||||
Information on the master cross-signing keys of the queried users.
|
||||
A map from user ID, to master key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`, along with the signatures
|
||||
uploaded via `/keys/signatures/upload` that the requesting user
|
||||
is allowed to see.
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["master"],
|
||||
"keys": {
|
||||
"ed25519:base64+master+public+key": "base64+master+public+key",
|
||||
}
|
||||
}
|
||||
}
|
||||
self_signing_keys:
|
||||
type: object
|
||||
description: |-
|
||||
Information on the self-signing keys of the queried users. A map
|
||||
from user ID, to self-signing key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`.
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["self_signing"],
|
||||
"keys": {
|
||||
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
user_signing_keys:
|
||||
type: object
|
||||
description: |-
|
||||
Information on the user-signing key of the user making the
|
||||
request, if they queried their own device information. A map
|
||||
from user ID, to user-signing key information. The
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`.
|
||||
additionalProperties:
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["user_signing"],
|
||||
"keys": {
|
||||
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
|
||||
},
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
"/keys/claim":
|
||||
post:
|
||||
summary: Claim one-time encryption keys.
|
||||
description: |-
|
||||
Claims one-time keys for use in pre-key messages.
|
||||
operationId: claimKeys
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: query
|
||||
description: |-
|
||||
Query defining the keys to be claimed
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
timeout:
|
||||
type: integer
|
||||
description: |-
|
||||
The time (in milliseconds) to wait when downloading keys from
|
||||
remote servers. 10 seconds is the recommended default.
|
||||
example: 10000
|
||||
one_time_keys:
|
||||
type: object
|
||||
description: |-
|
||||
The keys to be claimed. A map from user ID, to a map from
|
||||
device ID to algorithm name.
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: algorithm
|
||||
example: "signed_curve25519"
|
||||
example: {
|
||||
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
|
||||
}
|
||||
required:
|
||||
- one_time_keys
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The claimed keys.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
failures:
|
||||
type: object
|
||||
description: |-
|
||||
If any remote homeservers could not be reached, they are
|
||||
recorded here. The names of the properties are the names of
|
||||
the unreachable servers.
|
||||
|
||||
If the homeserver could be reached, but the user or device
|
||||
was unknown, no failure is recorded. Instead, the corresponding
|
||||
user or device is missing from the `one_time_keys` result.
|
||||
additionalProperties:
|
||||
type: object
|
||||
example: {}
|
||||
one_time_keys:
|
||||
type: object
|
||||
description: |-
|
||||
One-time keys for the queried devices. A map from user ID, to a
|
||||
map from devices to a map from `<algorithm>:<key_id>` to the key object.
|
||||
|
||||
See the [key algorithms](/client-server-api/#key-algorithms) section for information
|
||||
on the Key Object format.
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type:
|
||||
- string
|
||||
- object
|
||||
# XXX: We can't define an actual object here, so we have to hope
|
||||
# that people will look at the swagger source or can figure it out
|
||||
# from the other endpoints/example.
|
||||
# - type: object
|
||||
# title: KeyObject
|
||||
# properties:
|
||||
# key:
|
||||
# type: string
|
||||
# description: The key, encoded using unpadded base64.
|
||||
# signatures:
|
||||
# type: object
|
||||
# description: |-
|
||||
# Signature for the device. Mapped from user ID to signature object.
|
||||
# additionalProperties:
|
||||
# type: string
|
||||
# required: ['key', 'signatures']
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"JLAFKJWSCS": {
|
||||
"signed_curve25519:AAAAHg": {
|
||||
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
|
||||
"signatures": {
|
||||
"@alice:example.com": {
|
||||
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
required: ['one_time_keys']
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
"/keys/changes":
|
||||
get:
|
||||
summary: Query users with recent device key updates.
|
||||
description: |-
|
||||
Gets a list of users who have updated their device identity keys since a
|
||||
previous sync token.
|
||||
|
||||
The server should include in the results any users who:
|
||||
|
||||
* currently share a room with the calling user (ie, both users have
|
||||
membership state `join`); *and*
|
||||
* added new device identity keys or removed an existing device with
|
||||
identity keys, between `from` and `to`.
|
||||
operationId: getKeysChanges
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: from
|
||||
type: string
|
||||
description: |-
|
||||
The desired start point of the list. Should be the `next_batch` field
|
||||
from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientr0sync). Users who have not
|
||||
uploaded new device identity keys since this point, nor deleted
|
||||
existing devices with identity keys since then, will be excluded
|
||||
from the results.
|
||||
required: true
|
||||
x-example: "s72594_4483_1934"
|
||||
- in: query
|
||||
name: to
|
||||
type: string
|
||||
description: |-
|
||||
The desired end point of the list. Should be the `next_batch`
|
||||
field from a recent call to [`/sync`](/client-server-api/#get_matrixclientr0sync) - typically the most recent
|
||||
such call. This may be used by the server as a hint to check its
|
||||
caches are up to date.
|
||||
required: true
|
||||
x-example: "s75689_5632_2435"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The list of users who updated their devices.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
changed:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |-
|
||||
The Matrix User IDs of all users who updated their device
|
||||
identity keys.
|
||||
example: ["@alice:example.com", "@bob:example.org"]
|
||||
left:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |-
|
||||
The Matrix User IDs of all users who may have left all
|
||||
the end-to-end encrypted rooms they previously shared
|
||||
with the user.
|
||||
example: ["@clara:example.com", "@doug:example.org"]
|
||||
tags:
|
||||
- End-to-end encryption
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue