Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-29 22:04:08 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Upgrade Swagger data to OpenAPI 3.1 (#1310)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-06-07 14:16:29 +02:00 committed by GitHub
parent c64a616d54
commit 45b6aaf07a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
118 changed files with 15064 additions and 12727 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/internal/newsfragments/1310.feature Normal file
View file

@ -0,0 +1 @@
Upgrade Swagger data to OpenAPI 3.1.

49
data/api/application-service/ping.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.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
title: Matrix Application Service API
version: 1.0.0
paths:
"/ping":
/ping:
post:
x-addedInMatrixVersion: "1.7"
summary: Ping the application service
@ -39,10 +30,9 @@ paths:
operationId: ping
security:
- homeserverAccessToken: []
parameters:
- in: body
name: body
description: Ping body with optional transaction ID.
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -54,10 +44,29 @@ paths:
description: |-
A transaction ID for the ping, copied directly from the
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
description: Ping body with optional transaction ID.
responses:
200:
"200":
description: The provided `hs_token` is valid and the ping request was successful.
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

253
data/api/application-service/protocols.yaml
View file

@ -11,25 +11,15 @@
# 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'
openapi: 3.1.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
title: Matrix Application Service API
version: 1.0.0
paths:
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
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
@ -40,42 +30,53 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: "irc"
example: irc
schema:
type: string
responses:
200:
"200":
description: The protocol was found and metadata returned.
content:
application/json:
schema:
$ref: definitions/protocol.yaml
401:
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No protocol was found with the given path.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples:
application/json: {
response:
value: {
"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.
@ -89,102 +90,126 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
example: irc
schema:
type: string
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
schema:
type: string
responses:
200:
"200":
description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
401:
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No users were found with the given parameters.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples:
application/json: {
response:
value: {
"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.
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
example: irc
schema:
type: string
- 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.
schema:
type: string
responses:
200:
"200":
description: At least one portal room was found.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
401:
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
/thirdparty/location:
get:
summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |-
@ -196,84 +221,118 @@ paths:
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
schema:
type: string
responses:
200:
description: |-
All found third-party locations.
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
401:
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
/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.
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.
schema:
type: string
responses:
200:
description: |-
An array of third-party users.
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
401:
"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"
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"404":
description: No mappings were found with the given parameters.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

80
data/api/application-service/query_room.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.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
title: Matrix Application Service API
version: 1.0.0
paths:
"/rooms/{roomAlias}":
get:
@ -43,48 +32,75 @@ paths:
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
example: "#magicforest:example.com"
schema:
type: string
responses:
200:
"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: {}
content:
application/json:
schema:
type: object
401:
examples:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
"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"
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

80
data/api/application-service/query_user.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.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
title: Matrix Application Service API
version: 1.0.0
paths:
"/users/{userId}":
get:
@ -43,45 +32,72 @@ paths:
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"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: {}
content:
application/json:
schema:
type: object
401:
examples:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
"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"
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

67
data/api/application-service/transactions.yaml
View file

@ -12,19 +12,10 @@
# 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'
openapi: 3.1.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
title: Matrix Application Service API
version: 1.0.0
paths:
"/transactions/{txnId}":
put:
@ -42,35 +33,59 @@ paths:
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
example: "35"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member.yaml"},
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
{
"$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.
description: A list of events, formatted as per the Client-Server API.
items:
$ref: "../client-server/definitions/client_event.yaml"
required: ["events"]
$ref: ../client-server/definitions/client_event.yaml
required:
- events
description: Transaction information
responses:
200:
"200":
description: The transaction was processed successfully.
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

285
data/api/client-server/account-data.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Client Config API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Client Config API
version: 1.0.0
paths:
"/user/{userId}/account_data/{type}":
put:
@ -40,71 +29,85 @@ paths:
- 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
example: "@alice:example.com"
schema:
type: string
- in: path
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.
example: org.example.custom.config
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
"custom_account_data_key": "custom_config_value"
}
description: The content of the account data.
required: true
responses:
200:
description:
The account data was successfully added.
examples:
application/json: {}
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
400:
examples:
response:
value: {}
"400":
description: |-
The request body is not a JSON object. Errcode: `M_BAD_JSON`
or `M_NOT_JSON`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
tags:
- User data
get:
@ -117,51 +120,61 @@ paths:
- 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
example: "@alice:example.com"
schema:
type: string
- in: path
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"
example: org.example.custom.config
schema:
type: string
responses:
200:
description:
The account data content for the given type.
"200":
description: The account data content for the given type.
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
403:
"custom_account_data_key": "custom_config_value"
}
"403":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
"404":
description: |-
No account data has been provided for this user with the given `type`.
Errcode: `M_NOT_FOUND`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
@ -176,79 +189,93 @@ paths:
- 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
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
required: true
description: |-
The ID of the room to set account data on.
x-example: "!726s6s6q:example.com"
- in: path
description: The ID of the room to set account data on.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
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.
example: org.example.custom.room.config
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"}
"custom_account_data_key": "custom_account_data_value"
}
description: The content of the account data.
required: true
responses:
200:
description:
The account data was successfully added.
examples:
application/json: {}
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
400:
examples:
response:
value: {}
"400":
description: |-
The request body is not a JSON object (errcode `M_BAD_JSON` or
`M_NOT_JSON`), or the given `roomID` is not a valid room ID
(errcode `M_INVALID_PARAM`).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
get:
@ -261,65 +288,93 @@ paths:
- 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
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
required: true
description: |-
The ID of the room to get account data for.
x-example: "!726s6s6q:example.com"
- in: path
description: The ID of the room to get account data for.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
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"
example: org.example.custom.room.config
schema:
type: string
responses:
200:
description:
The account data content for the given type.
"200":
description: The account data content for the given type.
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
400:
description: |-
The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`.
"custom_account_data_key": "custom_config_value"
}
"400":
description: "The given `roomID` is not a valid room ID. Errcode:
`M_INVALID_PARAM`."
content:
application/json:
examples:
application/json: {
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
403:
"403":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
"404":
description: |-
No account data has been provided for this user and this room with the
given `type`. Errcode: `M_NOT_FOUND`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
tags:
- User data
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

120
data/api/client-server/admin.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Administration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Administration API
version: 1.0.0
paths:
"/admin/whois/{userId}":
get:
@ -41,16 +30,58 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user to look up.
required: true
x-example: "@peter:rabbit.rocks"
example: "@peter:rabbit.rocks"
schema:
type: string
responses:
200:
"200":
description: The lookup was successful.
content:
application/json:
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.
examples:
application/json: {
response:
value: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
@ -73,43 +104,20 @@ paths:
}
}
}
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
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

383
data/api/client-server/administrative_contact.yaml
View file

@ -12,23 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Account Administrative Contact API
version: 1.0.0
paths:
"/account/3pid":
/account/3pid:
get:
summary: Gets a list of a user's third-party identifiers.
description: |-
@ -44,19 +33,10 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The lookup was successful.
examples:
application/json: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
content:
application/json:
schema:
type: object
properties:
@ -69,7 +49,9 @@ paths:
medium:
type: string
description: The medium of the third-party identifier.
enum: ["email", "msisdn"]
enum:
- email
- msisdn
address:
type: string
description: The third-party identifier address.
@ -82,10 +64,25 @@ paths:
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']
description: The timestamp, in milliseconds, when the homeserver associated the
third-party identifier with the user.
required:
- medium
- address
- validated_at
- added_at
examples:
response:
value: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
tags:
- Account management
post:
@ -105,15 +102,14 @@ paths:
deprecated: true
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
three_pid_creds:
title: "ThreePidCredentials"
title: ThreePidCredentials
type: object
description: The third-party credentials to associate with the account.
properties:
@ -132,8 +128,13 @@ paths:
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"]
required:
- client_secret
- id_server
- id_access_token
- sid
required:
- three_pid_creds
example: {
"three_pid_creds": {
"id_server": "matrix.org",
@ -142,13 +143,12 @@ paths:
"client_secret": "d0nt-T3ll"
}
}
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {
"submit_url": "https://example.org/path/to/submitToken"
}
content:
application/json:
schema:
type: object
properties:
@ -168,19 +168,27 @@ paths:
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.
example: https://example.org/path/to/submitToken
examples:
application/json: {
response:
value: {
"submit_url": "https://example.org/path/to/submitToken"
}
"403":
description: The credentials could not be verified with the identity server.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"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:
- Account management
"/account/3pid/add":
/account/3pid/add:
post:
summary: Adds contact information to the user's account.
description: |-
@ -194,10 +202,9 @@ paths:
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -206,35 +213,44 @@ paths:
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
client_secret:
type: string
description: The client secret used in the session with the homeserver.
example: "d0nt-T3ll"
example: d0nt-T3ll
sid:
type: string
description: The session identifier given by the homeserver.
example: "abc123987"
required: ["client_secret", "sid"]
example: abc123987
required:
- client_secret
- sid
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
content:
application/json:
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
429:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/account/3pid/bind":
/account/3pid/bind:
post:
summary: Binds a 3PID to the user's account through an Identity Service.
description: |-
@ -248,10 +264,9 @@ paths:
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -263,32 +278,41 @@ paths:
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server.
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"]
required:
- client_secret
- id_server
- id_access_token
- sid
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0nt-T3ll"
}
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
content:
application/json:
schema:
type: object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/account/3pid/delete":
/account/3pid/delete:
post:
summary: Deletes a third-party identifier from the user's account
description: |-
@ -301,10 +325,9 @@ paths:
operationId: delete3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -315,32 +338,37 @@ paths:
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"
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The homeserver has disassociated the third-party identifier from the
user.
content:
application/json:
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"
- 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
@ -348,12 +376,12 @@ paths:
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"
example: success
required:
- id_server_unbind_result
tags:
- Account management
"/account/3pid/unbind":
/account/3pid/unbind:
post:
summary: Removes a user's third-party identifier from an identity server.
description: |-
@ -366,10 +394,9 @@ paths:
operationId: unbind3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -380,46 +407,52 @@ paths:
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"
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The identity server has disassociated the third-party identifier from the
user.
content:
application/json:
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"
- 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"
example: success
required:
- id_server_unbind_result
tags:
- Account management
"/account/3pid/email/requestToken":
/account/3pid/email/requestToken:
post:
summary: Begins the validation process for an email address for association with the user's account.
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
@ -430,49 +463,58 @@ paths:
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
requestBody:
content:
application/json:
schema:
$ref: "definitions/request_email_validation.yaml"
$ref: definitions/request_email_validation.yaml
required: true
responses:
200:
"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.
content:
application/json:
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:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/account/3pid/msisdn/requestToken":
/account/3pid/msisdn/requestToken:
post:
summary: Begins the validation process for a phone number for association with the user's account.
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
@ -483,40 +525,63 @@ paths:
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
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
"200":
description: An SMS message was sent to the given phone number.
content:
application/json:
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:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

120
data/api/client-server/appservice_ping.yaml
View file

@ -11,29 +11,16 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Application Service Ping API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
title: Matrix Client-Server Application Service Ping API
version: 1.0.0
paths:
"/appservice/{appserviceId}/ping":
post:
x-addedInMatrixVersion: "1.7"
summary: |-
Ask the homeserver to ping the application service to ensure the connection works.
summary: Ask the homeserver to ping the application service to ensure the
connection works.
description: |-
This API asks the homeserver to call the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
@ -48,31 +35,35 @@ paths:
operationId: pingAppservice
parameters:
- in: path
type: string
name: appserviceId
description: |-
The appservice ID of the appservice to ping. This must be the same
as the appservice whose `as_token` is being used to authenticate the
request.
required: true
x-example: "telegram"
- in: body
name: body
required: true
example: telegram
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
transaction_id:
type: string
description: |-
An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.
example: "mautrix-go_1683636478256400935_123"
description: An optional transaction ID that is passed through to the
`/_matrix/app/v1/ping` call.
example: mautrix-go_1683636478256400935_123
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
"200":
description: The ping was successful.
content:
application/json:
schema:
type: object
properties:
@ -85,26 +76,38 @@ paths:
required:
- duration_ms
examples:
application/json: {"duration_ms": 123}
400:
description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`.
response:
value: {
"duration_ms": 123
}
"400":
description: The application service doesn't have a URL configured. The errcode
is `M_URL_NOT_SET`.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_URL_NOT_SET",
"error": "Application service doesn't have a URL configured"
}
403:
description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`.
"403":
description: The access token used to authenticate the request doesn't belong to
an appservice, or belongs to a different appservice than the one in
the path. The errcode is `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Provided access token is not the appservice's as_token"
}
502:
"502":
description: |-
The application service returned a bad status, or the connection failed.
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
@ -112,6 +115,8 @@ paths:
For bad statuses, the response may include `status` and `body`
fields containing the HTTP status code and response body text
respectively to aid with debugging.
content:
application/json:
schema:
type: object
title: Error
@ -120,7 +125,9 @@ paths:
errcode:
type: string
description: An error code.
enum: [M_BAD_STATUS, M_CONNECTION_FAILED]
enum:
- M_BAD_STATUS
- M_CONNECTION_FAILED
error:
type: string
description: A human-readable error message.
@ -132,21 +139,44 @@ paths:
body:
type: string
description: The HTTP response body returned by the appservice.
example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
required: ["errcode"]
example: '{"errcode": "M_UNKNOWN_TOKEN"}'
required:
- errcode
examples:
application/json: {
response:
value: {
"errcode": "M_BAD_STATUS",
"error": "Ping returned status 401",
"status": 401,
"body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
}
504:
description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`.
"504":
description: The connection to the application service timed out. The errcode is
`M_CONNECTION_TIMEOUT`.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_CONNECTION_TIMEOUT",
"error": "Connection to application service timed out"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

72
data/api/client-server/appservice_room_directory.yaml
View file

@ -11,28 +11,14 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Application Service Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
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
title: Matrix Client-Server Application Service Room Directory API
version: 1.0.0
paths:
"/directory/list/appservice/{networkId}/{roomId}":
put:
summary: |-
Updates a room's visibility in the application service's room directory.
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.
@ -46,43 +32,69 @@ paths:
operationId: updateAppserviceRoomDirectoryVisibility
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
example: irc
schema:
type: string
- in: path
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:example.org"
- in: body
name: body
required: true
example: "!somewhere:example.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
enum:
- public
- private
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
example: public
required:
- visibility
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
"200":
description: The room's directory visibility has been updated.
content:
application/json:
schema:
type: object
examples:
application/json: {}
response:
value: {}
tags:
- Application service room directory management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

110
data/api/client-server/banning.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Banning API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Banning API
version: 1.0.0
paths:
"/rooms/{roomId}/ban":
post:
@ -41,14 +30,15 @@ paths:
- 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
example: "!e42d8c:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -63,29 +53,37 @@ paths:
x-addedInMatrixVersion: "1.1"
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"]
`reason` on the target's updated
[`m.room.member`](/client-server-api/#mroommember) event.
required:
- user_id
required: true
responses:
200:
"200":
description: The user has been kicked and banned from the room.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
403:
examples:
response:
value: {}
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"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":
@ -101,14 +99,16 @@ paths:
- 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
description: The room identifier (not alias) from which the user should be
unbanned.
required: true
example: "!e42d8c:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -125,26 +125,48 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
required:
- user_id
required: true
responses:
200:
"200":
description: The user has been unbanned from the room.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
403:
examples:
response:
value: {}
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"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
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

141
data/api/client-server/capabilities.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Capabilities API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Capabilities API
version: 1.0.0
paths:
"/capabilities":
/capabilities:
get:
summary: Gets information about the server's capabilities.
description: |-
@ -34,13 +25,61 @@ paths:
operationId: getCapabilities
security:
- accessToken: []
parameters: []
responses:
200:
description:
The capabilities of the server.
"200":
description: The capabilities of the server.
content:
application/json:
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
examples:
application/json: {
response:
value: {
"capabilities": {
"m.change_password": {
"enabled": false
@ -59,54 +98,26 @@ paths:
}
}
}
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:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Capabilities
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

667
data/api/client-server/content-repo.yaml
View file

File diff suppressed because it is too large Load diff

85
data/api/client-server/create_room.yaml
View file

@ -12,23 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Creation API
version: 1.0.0
paths:
"/createRoom":
/createRoom:
post:
summary: Create a new room
description: |-
@ -76,11 +65,9 @@ paths:
operationId: createRoom
security:
- accessToken: []
parameters:
- in: body
name: body
description: The desired room configuration.
required: true
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -95,7 +82,9 @@ paths:
properties:
visibility:
type: string
enum: ["public", "private"]
enum:
- public
- private
description: |-
A `public` visibility indicates that the room will be shown
in the published room list. A `private` visibility will hide
@ -146,7 +135,8 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
@ -161,7 +151,11 @@ paths:
address:
type: string
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
required:
- id_server
- id_access_token
- medium
- address
room_version:
type: string
description: |-
@ -201,10 +195,15 @@ paths:
content:
type: object
description: The content of the event.
required: ["type", "content"]
required:
- type
- content
preset:
type: string
enum: ["private_chat", "public_chat", "trusted_private_chat"]
enum:
- private_chat
- public_chat
- trusted_private_chat
description: |-
Convenience parameter for setting various default state events
based on a preset.
@ -228,23 +227,28 @@ paths:
[`m.room.power_levels`](/client-server-api/#mroompower_levels)
event content prior to it being sent to the room. Defaults to
overriding nothing.
description: The desired room configuration.
required: true
responses:
200:
"200":
description: Information about the newly created room.
content:
application/json:
schema:
type: object
description: Information about the newly created room.
properties:
room_id:
type: string
description: |-
The created room's ID.
required: ['room_id']
description: The created room's ID.
required:
- room_id
examples:
application/json: {
response:
value: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
400:
"400":
description: |-
The request is invalid. A meaningful `errcode` and description
@ -266,7 +270,24 @@ paths:
of a homeserver which does not support the requested room version.
The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these
cases.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
tags:
- Room creation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

121
data/api/client-server/cross_signing.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Cross Signing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Cross Signing API
version: 1.0.0
paths:
"/keys/device_signing/upload":
/keys/device_signing/upload:
post:
x-addedInMatrixVersion: "1.1"
summary: Upload cross-signing keys.
@ -38,18 +27,14 @@ paths:
operationId: uploadCrossSigningKeys
security:
- accessToken: []
parameters:
- in: body
name: keys
description: |-
The keys to be published.
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
master_key:
description: |-
Optional. The user\'s master key.
description: Optional. The user\'s master key.
allOf:
- $ref: definitions/cross_signing_key.yaml
self_signing_key:
@ -73,7 +58,7 @@ paths:
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
example: {
"auth": {
"type": "example.type.foo",
@ -82,16 +67,20 @@ paths:
},
"master_key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
"ed25519:base64+master+public+key": "base64+master+public+key"
}
},
"self_signing_key": {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"usage": [
"self_signing"
],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
@ -101,9 +90,11 @@ paths:
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"usage": [
"user_signing"
],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
@ -112,13 +103,17 @@ paths:
}
}
}
description: The keys to be published.
required: true
responses:
200:
"200":
description: The provided keys were successfully uploaded.
content:
application/json:
schema:
type: object
example: {}
400:
"400":
description: |-
The input was invalid in some way. This can include one of the
following error codes:
@ -126,16 +121,20 @@ paths:
* `M_INVALID_SIGNATURE`: For example, the self-signing or
user-signing key had an incorrect signature.
* `M_MISSING_PARAM`: No master key is available.
content:
application/json:
schema:
type: object
example: {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
403:
"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.
content:
application/json:
schema:
type: object
example: {
@ -144,7 +143,7 @@ paths:
}
tags:
- End-to-end encryption
"/keys/signatures/upload":
/keys/signatures/upload:
post:
x-addedInMatrixVersion: "1.1"
summary: Upload cross-signing signatures.
@ -158,13 +157,9 @@ paths:
operationId: uploadCrossSigningSignatures
security:
- accessToken: []
parameters:
- in: body
name: signatures
description: |-
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
requestBody:
content:
application/json:
schema:
type: object
title: Signatures
@ -193,7 +188,9 @@ paths:
},
"base64+master+public+key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
},
@ -210,7 +207,9 @@ paths:
"keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
},
"usage": ["master"],
"usage": [
"master"
],
"signatures": {
"@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
@ -219,9 +218,15 @@ paths:
}
}
}
description: |-
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
responses:
200:
"200":
description: The provided signatures were processed.
content:
application/json:
schema:
type: object
properties:
@ -236,13 +241,25 @@ paths:
additionalProperties:
type: object
title: Error
example: {
"@alice:example.com": {
"HIJKLMN": {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
}
}
example:
"@alice:example.com":
HIJKLMN:
errcode: M_INVALID_SIGNATURE
error: Invalid signature
tags:
- End-to-end encryption
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

2
data/api/client-server/definitions/push_condition.yaml
View file

@ -30,7 +30,7 @@ properties:
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
example: content.body
pattern:
type: string
description: |-

6
data/api/client-server/definitions/push_rule.yaml
View file

@ -17,9 +17,9 @@ type: object
properties:
actions:
items:
type:
- object
- string
oneOf:
- type: object
- type: string
type: array
description: |-
The actions to perform when this rule is matched.

165
data/api/client-server/device_management.yaml
View file

@ -11,34 +11,23 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server device management API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server device management API
version: 1.0.0
paths:
"/devices":
/devices:
get:
summary: List registered devices for the current user
description: |-
Gets information about all devices for the current user.
description: Gets information about all devices for the current user.
operationId: getDevices
security:
- accessToken: []
responses:
200:
"200":
description: Device information
content:
application/json:
schema:
type: object
properties:
@ -48,9 +37,10 @@ paths:
items:
type: object
allOf:
- $ref: "definitions/client_device.yaml"
- $ref: definitions/client_device.yaml
examples:
application/json: {
response:
value: {
"devices": [
{
"device_id": "QBUAZIFURK",
@ -65,54 +55,56 @@ paths:
"/devices/{deviceId}":
get:
summary: Get a single device
description: |-
Gets information on a single device, by device id.
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"
example: QBUAZIFURK
schema:
type: string
responses:
200:
"200":
description: Device information
content:
application/json:
schema:
type: object
allOf:
- $ref: "definitions/client_device.yaml"
- $ref: definitions/client_device.yaml
examples:
application/json: {
response:
value: {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
404:
"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.
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.
example: QBUAZIFURK
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -121,16 +113,22 @@ paths:
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: {
example: {
"display_name": "My other phone"
}
description: New information for the device.
required: true
responses:
"200":
description: The device was successfully updated.
content:
application/json:
schema:
type: object # empty json object
404:
examples:
response:
value: {}
"404":
description: The current user has no device with the given ID.
tags:
- Device management
@ -145,14 +143,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: deviceId
description: The device to delete.
required: true
x-example: "QBUAZIFURK"
- in: body
name: body
required: true
example: QBUAZIFURK
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -161,25 +160,29 @@ paths:
Additional authentication information for the
user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
required: true
responses:
200:
"200":
description: |-
The device was successfully removed, or had been removed
previously.
content:
application/json:
schema:
type: object
examples:
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
$ref: definitions/auth_response.yaml
tags:
- Device management
"/delete_devices":
/delete_devices:
post:
summary: Bulk deletion of devices
description: |-
@ -189,10 +192,9 @@ paths:
operationId: deleteDevices
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -202,29 +204,50 @@ paths:
items:
type: string
description: A list of device IDs.
example: ["QBUAZIFURK", "AUIECTSRND"]
example:
- QBUAZIFURK
- AUIECTSRND
auth:
allOf:
- "$ref": "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
description: |-
Additional authentication information for the
user-interactive authentication API.
required:
- devices
required: true
responses:
200:
"200":
description: |-
The devices were successfully removed, or had been removed
previously.
content:
application/json:
schema:
type: object
examples:
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
$ref: definitions/auth_response.yaml
tags:
- Device management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

210
data/api/client-server/directory.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Directory API
version: 1.0.0
paths:
"/directory/room/{roomAlias}":
put:
@ -35,52 +24,64 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomAlias
description: |
The room alias to set. Its format is defined
[in the appendices](/appendices/#room-aliases).
required: true
x-example: "#monkeys:matrix.org"
- in: body
name: body
description: Information about this room alias.
required: true
example: "#monkeys:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The room ID to set.
required: ['room_id']
required:
- room_id
example: {
"room_id": "!abnjk1jdasj98:capuchins.com"
}
description: Information about this room alias.
required: true
responses:
200:
"200":
description: The mapping was created.
examples:
application/json: {}
content:
application/json:
schema:
type: object
400:
description: The given `roomAlias` is not a valid room alias.
examples:
application/json: {
response:
value: {}
"400":
description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
schema:
"$ref": "definitions/errors/error.yaml"
409:
"409":
description: A room alias with that name already exists.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
get:
@ -91,20 +92,22 @@ paths:
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. Its format is defined
[in the appendices](/appendices/#room-aliases).
required: true
x-example: "#monkeys:matrix.org"
example: "#monkeys:matrix.org"
schema:
type: string
responses:
200:
"200":
description: The room ID and other information for this alias.
content:
application/json:
schema:
type: object
properties:
@ -118,7 +121,8 @@ paths:
type: string
description: A server which is aware of this room alias.
examples:
application/json: {
response:
value: {
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
@ -126,24 +130,30 @@ paths:
"another.com"
]
}
400:
"400":
description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
"404":
description: There is no mapped room ID for this room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
delete:
@ -160,36 +170,41 @@ paths:
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. Its format is defined
[in the appendices](/appendices/#room-aliases).
required: true
x-example: "#monkeys:matrix.org"
example: "#monkeys:matrix.org"
schema:
type: string
responses:
200:
"200":
description: The mapping was deleted.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: {
response:
value: {}
"404":
description: There is no mapped room ID for this room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
"/rooms/{roomId}/aliases":
@ -212,29 +227,22 @@ paths:
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"
example: "!abc123:example.org"
schema:
type: string
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"
]
}
"200":
description: The list of local aliases for the room.
content:
application/json:
schema:
type: object
properties:
@ -243,28 +251,62 @@ paths:
description: The server's local aliases on the room. Can be empty.
items:
type: string
required: ['aliases']
400:
description: The given `roomAlias` is not a valid room alias.
required:
- aliases
examples:
application/json: {
response:
value: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
"400":
description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
"403":
description: The user is not permitted to retrieve the list of local aliases for
the room.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: The user is not permitted to retrieve the list of local aliases for the room.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not a member of the room."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room directory
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

79
data/api/client-server/event_context.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Event Context API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Event Context API
version: 1.0.0
paths:
"/rooms/{roomId}/context/{eventId}":
get:
@ -42,29 +31,31 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get events from.
required: true
x-example: "!636q39766251:example.com"
- in: path
example: "!636q39766251:example.com"
schema:
type: string
- in: path
name: eventId
description: The event to get context around.
required: true
x-example: "$f3h4d129462ha:example.com"
example: $f3h4d129462ha:example.com
schema:
type: string
- in: query
type: integer
name: limit
description: |-
The maximum number of context events to return. The limit applies
to the sum of the `events_before` and `events_after` arrays. The
requested event ID is always returned in `event` even if `limit` is
0. Defaults to 10.
x-example: 3
example: 3
schema:
type: integer
- 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
@ -73,49 +64,50 @@ paths:
homeserver prefers.
See [Filtering](/client-server-api/#filtering) for more information.
x-example: "66696p746572"
example: 66696p746572
schema:
type: string
responses:
200:
"200":
description: The events and state surrounding the requested event.
content:
application/json:
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.
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.
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:
$ref: "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
event:
description: |-
Details of the requested event.
description: Details of the requested event.
allOf:
- $ref: "definitions/client_event.yaml"
- $ref: definitions/client_event.yaml
events_after:
type: array
description: |-
A list of room events that happened just after the
requested event, in chronological order.
items:
$ref: "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
state:
type: array
description: |-
The state of the room at the last event returned.
description: The state of the room at the last event returned.
items:
$ref: "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
examples:
application/json: {
response:
value: {
"end": "t29-57_2_0_2",
"events_after": [
{
@ -148,3 +140,18 @@ paths:
}
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

213
data/api/client-server/filter.yaml
View file

@ -11,20 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server filter API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server filter API
version: 1.0.0
paths:
"/user/{userId}/filter":
post:
@ -38,49 +28,77 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description:
The id of the user uploading the filter. The access token must be
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.
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.yaml"
- $ref: definitions/sync_filter.yaml
example: {
"room": {
"state": {
"types": ["m.room.*"],
"not_rooms": ["!726s6s6q:example.com"]
"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"]
"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"]
"types": [
"m.receipt",
"m.typing"
],
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
]
}
},
"presence": {
"types": ["m.presence"],
"not_senders": ["@alice:example.com"]
"types": [
"m.presence"
],
"not_senders": [
"@alice:example.com"
]
},
"event_format": "client",
"event_fields": ["type", "content", "sender"]
"event_fields": [
"type",
"content",
"sender"
]
}
description: The filter to upload.
required: true
responses:
200:
"200":
description: The filter was created.
content:
application/json:
schema:
type: object
properties:
@ -91,8 +109,9 @@ paths:
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']
example: 66696p746572
required:
- filter_id
tags:
- Room participation
"/user/{userId}/filter/{filterId}":
@ -104,53 +123,95 @@ paths:
parameters:
- in: path
name: userId
type: string
description: |-
The user ID to download a filter for.
x-example: "@alice:example.com"
description: The user ID to download a filter for.
required: true
example: "@alice:example.com"
schema:
type: string
- in: path
name: filterId
type: string
description: |-
The filter ID to download.
x-example: "66696p746572"
description: The filter ID to download.
required: true
example: 66696p746572
schema:
type: string
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"]
}
"200":
description: The filter definition.
content:
application/json:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.yaml"
404:
description: "Unknown filter."
- $ref: definitions/sync_filter.yaml
examples:
response:
value: {
"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"
]
}
"404":
description: Unknown filter.
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

88
data/api/client-server/inviting.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Joining API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Joining API
version: 1.0.0
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.
@ -47,20 +36,20 @@ paths:
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
example: "!d41d8cd:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -77,16 +66,21 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
required:
- user_id
required: true
responses:
200:
description: The user has been invited to join the room, or was already invited to the room.
examples:
application/json: {
}
"200":
description: The user has been invited to join the room, or was already invited
to the room.
content:
application/json:
schema:
type: object
400:
examples:
response:
value: {}
"400":
description: |-
The request is invalid. A meaningful `errcode` and description
@ -98,9 +92,11 @@ paths:
- 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.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
403:
$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:
@ -108,14 +104,36 @@ paths:
- 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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

147
data/api/client-server/joining.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Inviting API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Inviting API
version: 1.0.0
paths:
"/rooms/{roomId}/join":
post:
@ -47,20 +36,21 @@ paths:
- 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
example: "!d41d8cd:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
third_party_signed:
allOf:
- $ref: "definitions/third_party_signed.yaml"
- $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
@ -71,24 +61,30 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
example: Looking for support
required: true
responses:
200:
"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"}
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
required:
- room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"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:
@ -96,15 +92,22 @@ paths:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
"/join/{roomIdOrAlias}":
@ -126,29 +129,33 @@ paths:
- 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:
example: "#monkeys:matrix.org"
schema:
type: string
- in: query
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
example:
- matrix.org
- elsewhere.ca
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
third_party_signed:
allOf:
- $ref: "definitions/third_party_signed.yaml"
- $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
@ -159,24 +166,30 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
example: Looking for support
required: true
responses:
200:
"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"}
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
required:
- room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"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:
@ -184,14 +197,36 @@ paths:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

768
data/api/client-server/key_backup.yaml
View file

File diff suppressed because it is too large Load diff

317
data/api/client-server/keys.yaml
View file

@ -13,36 +13,21 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Client Config API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Client Config API
version: 1.0.0
paths:
"/keys/upload":
/keys/upload:
post:
summary: Upload end-to-end encryption keys.
description: |-
Publishes end-to-end encryption keys for the device.
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
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -66,25 +51,18 @@ paths:
by the [key algorithm](/client-server-api/#key-algorithms).
May be absent if no new one-time keys are required.
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"
}
}
}
}
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
fallback_keys:
x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml"
@ -105,22 +83,21 @@ paths:
be included to denote that the key is a fallback key.
May be absent if a new fallback key is not required.
example: {
"curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAGj": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"fallback": true,
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
example:
curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8
signed_curve25519:AAAAGj:
key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
fallback: true
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
description: The keys to be published
required: true
responses:
200:
description:
The provided keys were successfully uploaded.
"200":
description: The provided keys were successfully uploaded.
content:
application/json:
schema:
type: object
properties:
@ -138,23 +115,18 @@ paths:
signed_curve25519: 20
required:
- one_time_key_counts
tags:
- End-to-end encryption
"/keys/query":
/keys/query:
post:
summary: Download device identity keys.
description: |-
Returns the current devices and identity keys for the given users.
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
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -174,16 +146,18 @@ paths:
type: array
items:
type: string
description: "device ID"
description: device ID
example:
"@alice:example.com": []
required:
- device_keys
description: Query defining the keys to be downloaded
required: true
responses:
200:
description:
The device information
"200":
description: The device information
content:
application/json:
schema:
type: object
properties:
@ -225,30 +199,23 @@ paths:
properties:
device_display_name:
type: string
description:
The display name which the user set on the device.
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"
}
}
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:
x-addedInMatrixVersion: "1.1"
type: object
@ -262,15 +229,13 @@ paths:
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",
}
}
}
example:
"@alice:example.com":
user_id: "@alice:example.com"
usage:
- master
keys:
ed25519:base64+master+public+key: base64+master+public+key
self_signing_keys:
x-addedInMatrixVersion: "1.1"
type: object
@ -282,20 +247,16 @@ paths:
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"
}
}
}
}
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: |-
@ -307,36 +268,28 @@ paths:
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"
}
}
}
}
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":
/keys/claim:
post:
summary: Claim one-time encryption keys.
description: |-
Claims one-time keys for use in pre-key messages.
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
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -356,16 +309,19 @@ paths:
additionalProperties:
type: string
description: algorithm
example: "signed_curve25519"
example: {
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
}
example: signed_curve25519
example:
"@alice:example.com":
JLAFKJWSCS: signed_curve25519
required:
- one_time_keys
description: Query defining the keys to be claimed
required: true
responses:
200:
description:
The claimed keys.
"200":
description: The claimed keys.
content:
application/json:
schema:
type: object
properties:
@ -403,24 +359,19 @@ paths:
# See also one_time_key parameter for /keys/upload above.
type: object
title: OneTimeKeys
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']
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":
/keys/changes:
get:
summary: Query users with recent device key updates.
description: |-
@ -439,7 +390,6 @@ paths:
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_matrixclientv3sync). Users who have not
@ -447,21 +397,25 @@ paths:
existing devices with identity keys since then, will be excluded
from the results.
required: true
x-example: "s72594_4483_1934"
example: s72594_4483_1934
schema:
type: string
- 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_matrixclientv3sync) - 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"
example: s75689_5632_2435
schema:
type: string
responses:
200:
description:
The list of users who updated their devices.
"200":
description: The list of users who updated their devices.
content:
application/json:
schema:
type: object
properties:
@ -472,7 +426,9 @@ paths:
description: |-
The Matrix User IDs of all users who updated their device
identity keys.
example: ["@alice:example.com", "@bob:example.org"]
example:
- "@alice:example.com"
- "@bob:example.org"
left:
type: array
items:
@ -481,6 +437,23 @@ paths:
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"]
example:
- "@clara:example.com"
- "@doug:example.org"
tags:
- End-to-end encryption
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

68
data/api/client-server/kicking.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Kicking API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Kicking API
version: 1.0.0
paths:
"/rooms/{roomId}/kick":
post:
@ -43,14 +32,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be kicked.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
example: "!e42d8c:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -66,16 +56,20 @@ paths:
description: |-
The reason the user has been kicked. This will be supplied as the
`reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
required: ["user_id"]
required:
- user_id
required: true
responses:
200:
"200":
description: The user has been kicked from the room.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
403:
examples:
response:
value: {}
"403":
description: |-
You do not have permission to kick the user from the room. A meaningful `errcode` and
description error text will be returned. Example reasons for rejections are:
@ -83,12 +77,30 @@ paths:
- The kicker is not currently in the room.
- The kickee is not currently in the room.
- The kicker's power level is insufficient to kick users from the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

110
data/api/client-server/knocking.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Knocking API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Knocking API
version: 1.0.0
paths:
"/knock/{roomIdOrAlias}":
post:
@ -52,23 +41,27 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomIdOrAlias
description: The room identifier or alias to knock upon.
required: true
x-example: "#monkeys:matrix.org"
- in: query
type: array
items:
example: "#monkeys:matrix.org"
schema:
type: string
- in: query
name: server_name
description: |-
The servers to attempt to knock on 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
example:
- matrix.org
- elsewhere.ca
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -77,49 +70,78 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
example: Looking for support
required: true
responses:
200:
"200":
description: |-
The room has been knocked upon.
The knocked room ID must be returned in the `room_id` field.
examples:
application/json: {
"room_id": "!d41d8cd:matrix.org"
}
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The knocked room ID.
required: ["room_id"]
403:
required:
- room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"403":
description: |-
You do not have permission to knock on the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The room is not set up for knocking.
- The user has been banned from the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room."
}
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: |-
The room could not be found or resolved to a room ID.
$ref: definitions/errors/error.yaml
examples:
application/json: {
"errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to knock on this room."
}
"404":
description: The room could not be found or resolved to a room ID.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
429:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "That room does not appear to exist."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

100
data/api/client-server/leaving.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Leaving API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Leaving API
version: 1.0.0
paths:
"/rooms/{roomId}/leave":
post:
@ -47,14 +36,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier to leave.
required: true
x-example: "!nkl290a:matrix.org"
- in: body
name: body
required: true
example: "!nkl290a:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -67,19 +57,23 @@ paths:
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: true
responses:
200:
description: |-
The room has been left.
examples:
application/json: {
}
"200":
description: The room has been left.
content:
application/json:
schema:
type: object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
"/rooms/{roomId}/forget":
@ -100,32 +94,54 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier to forget.
required: true
x-example: "!au1ba7o:matrix.org"
example: "!au1ba7o:matrix.org"
schema:
type: string
responses:
200:
description: |-
The room has been forgotten.
examples:
application/json: {
}
"200":
description: The room has been forgotten.
content:
application/json:
schema:
type: object
400:
description: The user has not left the room
examples:
application/json: {
response:
value: {}
"400":
description: The user has not left the room
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN",
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

50
data/api/client-server/list_joined_rooms.yaml
View file

@ -11,48 +11,54 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Listing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Listing API
version: 1.0.0
paths:
"/joined_rooms":
/joined_rooms:
get:
summary: Lists the user's current rooms.
description: |-
This API returns a list of the user's current rooms.
description: This API returns a list of the user's current rooms.
operationId: getJoinedRooms
security:
- accessToken: []
responses:
200:
"200":
description: A list of the rooms the user is in.
content:
application/json:
schema:
type: object
required: ["joined_rooms"]
required:
- joined_rooms
properties:
joined_rooms:
type: array
description: |-
The ID of each room in which the user has `joined` membership.
description: The ID of each room in which the user has `joined` membership.
items:
type: string
examples:
application/json: {
response:
value: {
"joined_rooms": [
"!foo:example.com"
]
}
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

155
data/api/client-server/list_public_rooms.yaml
View file

@ -11,56 +11,56 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
title: Matrix Client-Server Room Directory API
version: 1.0.0
paths:
"/directory/list/room/{roomId}":
get:
summary: Gets the visibility of a room in the directory
description: |-
Gets the visibility of a given room on the server's public room directory.
description: Gets the visibility of a given room on the server's public room
directory.
operationId: getRoomVisibilityOnDirectory
parameters:
- in: path
type: string
name: roomId
description: The room ID.
required: true
x-example: "!curbf:matrix.org"
example: "!curbf:matrix.org"
schema:
type: string
responses:
200:
"200":
description: The visibility of the room in the directory
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum: ['private', 'public']
enum:
- private
- public
description: The visibility of the room in the directory.
examples:
application/json: {
response:
value: {
"visibility": "public"
}
404:
"404":
description: The room is not known to the server
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room discovery
put:
@ -77,47 +77,56 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID.
required: true
x-example: "!curbf:matrix.org"
- in: body
name: body
required: true
description: |-
The new visibility for the room on the room directory.
example: "!curbf:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum: ["private", "public"]
enum:
- private
- public
description: |-
The new visibility setting for the room.
Defaults to 'public'.
example: {
"visibility": "public"
}
description: The new visibility for the room on the room directory.
required: true
responses:
200:
"200":
description: The visibility was updated, or no change was needed.
examples:
application/json: {}
content:
application/json:
schema:
type: object
404:
description: The room is not known to the server
examples:
application/json: {
response:
value: {}
"404":
description: The room is not known to the server
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room discovery
"/publicRooms":
/publicRooms:
get:
summary: Lists the public rooms on the server.
description: |-
@ -129,28 +138,32 @@ paths:
parameters:
- in: query
name: limit
description: Limit the number of results returned.
schema:
type: integer
description: |-
Limit the number of results returned.
- in: query
name: since
type: string
description: |-
A pagination token from a previous request, allowing clients to
get the next (or previous) batch of rooms.
The direction of pagination is specified solely by which token
is supplied, rather than via an explicit flag.
schema:
type: string
- in: query
name: server
type: string
description: |-
The server to fetch the public room lists from. Defaults to the
local server.
responses:
200:
description: A list of the rooms on the server.
schema:
$ref: "definitions/public_rooms_response.yaml"
type: string
responses:
"200":
description: A list of the rooms on the server.
content:
application/json:
schema:
$ref: definitions/public_rooms_response.yaml
tags:
- Room discovery
post:
@ -166,22 +179,20 @@ paths:
parameters:
- in: query
name: server
type: string
description: |-
The server to fetch the public room lists from. Defaults to the
local server.
- in: body
name: body
required: true
description: |-
Options for which rooms to return.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: |-
Limit the number of results returned.
description: Limit the number of results returned.
since:
type: string
description: |-
@ -191,9 +202,8 @@ paths:
rather than via an explicit flag.
filter:
type: object
title: "Filter"
description: |-
Filter to apply to the results.
title: Filter
description: Filter to apply to the results.
properties:
generic_search_term:
type: string
@ -221,20 +231,39 @@ paths:
description: |-
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
example: "irc"
example: irc
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"room_types": [null, "m.space"]
"room_types": [
null,
"m.space"
]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
description: Options for which rooms to return.
required: true
responses:
200:
"200":
description: A list of the rooms on the server.
content:
application/json:
schema:
$ref: "definitions/public_rooms_response.yaml"
$ref: definitions/public_rooms_response.yaml
tags:
- Room discovery
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

177
data/api/client-server/login.yaml
View file

@ -13,23 +13,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Registration and Login API
version: 1.0.0
paths:
"/login":
/login:
get:
summary: Get the supported login types to authenticate users
description: |-
@ -37,15 +26,10 @@ paths:
should pick one of these and supply it as the `type` when logging in.
operationId: getLoginFlows
responses:
200:
"200":
description: The login types the homeserver supports
examples:
application/json: {
"flows": [
{"type": "m.login.password"},
{"type": "m.login.token", "get_login_token": true}
]
}
content:
application/json:
schema:
type: object
properties:
@ -55,7 +39,8 @@ paths:
items:
type: object
title: LoginFlow
required: ['type']
required:
- type
properties:
type:
description: |-
@ -72,10 +57,25 @@ paths:
endpoint. Note that supporting the endpoint does not
necessarily indicate that the user attempting to log in will
be able to generate such a token.
429:
examples:
response:
value: {
"flows": [
{
"type": "m.login.password"
},
{
"type": "m.login.token",
"get_login_token": true
}
]
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Session management
post:
@ -92,10 +92,9 @@ paths:
invalidate any access token previously associated with that device. See
[Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
operationId: login
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -110,19 +109,25 @@ paths:
properties:
type:
type: string
enum: ["m.login.password", "m.login.token"]
enum:
- m.login.password
- m.login.token
description: The login type being used.
identifier:
"$ref": "definitions/user_identifier.yaml"
$ref: definitions/user_identifier.yaml
user:
type: string
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`.
description: The fully qualified user ID or just local part of the user ID, to
log in. Deprecated in favour of `identifier`.
medium:
type: string
description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
description: When logging in using a third-party identifier, the medium of the
identifier. Must be 'email'. Deprecated in favour of
`identifier`.
address:
type: string
description: Third-party identifier for the user. Deprecated in favour of `identifier`.
description: Third-party identifier for the user. Deprecated in favour of
`identifier`.
password:
type: string
description: |-
@ -130,8 +135,7 @@ paths:
password.
token:
type: string
description: |-
Required when `type` is `m.login.token`. Part of Token-based login.
description: Required when `type` is `m.login.token`. Part of Token-based login.
device_id:
type: string
description: |-
@ -148,30 +152,16 @@ paths:
if `device_id` corresponds to a known device.
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
description: If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
required: ["type"]
required:
- type
required: true
responses:
200:
"200":
description: The user has been authenticated.
examples:
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"refresh_token": "def456",
"expires_in_ms": 60000,
"device_id": "GHTYAJCE",
"well_known": {
"m.homeserver": {
"base_url": "https://example.org"
},
"m.identity_server": {
"base_url": "https://id.example.org"
}
}
}
content:
application/json:
schema:
type: object
properties:
@ -221,34 +211,77 @@ paths:
optionally validating the URLs within. This object takes the same
form as the one returned from .well-known autodiscovery.
allOf:
- "$ref": "definitions/wellknown/full.yaml"
required: ["access_token", "device_id", "user_id"]
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
- $ref: definitions/wellknown/full.yaml
required:
- access_token
- device_id
- user_id
examples:
application/json: {
response:
value: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"refresh_token": "def456",
"expires_in_ms": 60000,
"device_id": "GHTYAJCE",
"well_known": {
"m.homeserver": {
"base_url": "https://example.org"
},
"m.identity_server": {
"base_url": "https://id.example.org"
}
}
}
"400":
description: Part of the request was invalid. For example, the login type may
not be recognised.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
"403":
description: |-
The login attempt failed. This can include one of the following error codes:
* `M_FORBIDDEN`: The provided authentication data was incorrect
or the requested device ID is the same as a cross-signing key
ID.
* `M_USER_DEACTIVATED`: The user has been deactivated.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

94
data/api/client-server/login_token.yaml
View file

@ -11,25 +11,15 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Registration and Login API
version: 1.0.0
paths:
"/login/get_token":
/login/get_token:
post:
summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token.
summary: Optional endpoint to generate a single-use, time-limited,
`m.login.token` token.
description: |-
Optional endpoint - the server is not required to implement this endpoint if it does not
intend to use or support this functionality.
@ -64,29 +54,29 @@ paths:
x-addedInMatrixVersion: "1.7"
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
required: true
responses:
200:
description: The login token an unauthenticated client can use to log in as the requesting user.
examples:
application/json: {
"login_token": "<opaque string>",
"expires_in_ms": 120000
}
"200":
description: The login token an unauthenticated client can use to log in as the
requesting user.
content:
application/json:
schema:
type: object
required: ["login_token", "expires_in_ms"]
required:
- login_token
- expires_in_ms
properties:
login_token:
type: string
@ -96,23 +86,49 @@ paths:
description: |-
The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
(2 minutes) is recommended as a default.
400:
examples:
response:
value: {
"login_token": "<opaque string>",
"expires_in_ms": 120000
}
"400":
description: |-
The request was malformed, or the user does not have an ability to generate tokens for their devices,
as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token`
[capability](/client-server-api/#capabilities-negotiation).
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
$ref: definitions/errors/error.yaml
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
429:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

44
data/api/client-server/logout.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Registration and Login API
version: 1.0.0
paths:
"/logout":
/logout:
post:
summary: Invalidates a user access token
description: |-
@ -38,14 +27,16 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The access token used in the request was successfully invalidated.
content:
application/json:
schema:
type: object
properties: {}
tags:
- Session management
"/logout/all":
/logout/all:
post:
summary: Invalidates all access tokens for a user
description: |-
@ -64,10 +55,27 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The user's access tokens were successfully invalidated.
content:
application/json:
schema:
type: object
properties: {}
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

110
data/api/client-server/message_pagination.yaml
View file

@ -11,21 +11,10 @@
# 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"
openapi: 3.1.0
info:
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Rooms API
version: 1.0.0
paths:
"/rooms/{roomId}/messages":
get:
@ -41,16 +30,16 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get events from.
required: true
x-example: "!636q39766251:example.com"
- in: query
example: "!636q39766251:example.com"
schema:
type: string
- in: query
name: from
x-changedInMatrixVersion:
1.3: |
"1.3": |
Previously, this field was required and paginating from the first or
last visible event in the room history wasn't supported.
description: |-
@ -66,18 +55,19 @@ paths:
from the first or last (per the value of the `dir` parameter) visible
event in the room history for the requesting user.
required: false
x-example: "s345_678_333"
- in: query
example: s345_678_333
schema:
type: string
- in: query
name: to
description: |-
The token to stop returning events at. This token can be obtained from
a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
or from an `end` token returned by a previous request to this endpoint.
required: false
- in: query
schema:
type: string
enum: ["b", "f"]
- in: query
name: dir
description: |-
The direction to return events from. If this is set to `f`, events
@ -85,23 +75,29 @@ paths:
is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`.
required: true
x-example: "b"
- in: query
type: integer
name: limit
description: |-
The maximum number of events to return. Default: 10.
x-example: "3"
- in: query
example: b
schema:
type: string
enum:
- b
- f
- in: query
name: limit
description: "The maximum number of events to return. Default: 10."
example: "3"
schema:
type: integer
- in: query
name: filter
description: |-
A JSON RoomEventFilter to filter returned events with.
x-example: |-
{"contains_url":true}
description: A JSON RoomEventFilter to filter returned events with.
example: '{"contains_url":true}'
schema:
type: string
responses:
200:
"200":
description: A list of messages with a new token to request more.
content:
application/json:
schema:
type: object
description: A list of messages with a new token to request more.
@ -133,7 +129,7 @@ paths:
are available. Clients should continue to paginate until no `end` property
is returned.
items:
"$ref": "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
state:
type: array
description: |-
@ -146,31 +142,47 @@ paths:
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
$ref: "definitions/client_event.yaml"
required: [start, chunk]
$ref: definitions/client_event.yaml
required:
- start
- chunk
examples:
application/json:
{
response:
value: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk":
[
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.name.yaml",
"$ref": "../../event-schemas/examples/m.room.name.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml",
},
],
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
403:
description: >
]
}
"403":
description: |
You aren't a member of the room.
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

109
data/api/client-server/notifications.yaml
View file

@ -11,24 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Notifications API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Notifications API
version: 1.0.0
paths:
"/notifications":
/notifications:
get:
summary: Gets a list of events that the user has been notified about
description: |-
@ -39,52 +27,40 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: from
description: |-
Pagination token to continue from. This should be the `next_token`
returned from an earlier call to this endpoint.
required: false
x-example: "xxxxx"
example: xxxxx
schema:
type: string
- in: query
type: integer
name: limit
description: Limit on the number of events to return in this request.
required: false
x-example: 20
example: 20
schema:
type: integer
- in: query
name: only
type: string
description: |-
Allows basic filtering of events returned. Supply `highlight`
to return only events where the notification had the highlight
tweak set.
required: false
x-example: "highlight"
example: highlight
schema:
type: string
responses:
200:
"200":
description: A batch of events is being returned
examples:
application/json: {
"next_token": "abcdef",
"notifications": [
{
"actions": [
"notify"
],
"profile_tag": "hcbvkzxhcvb",
"read": true,
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
}
]
}
content:
application/json:
schema:
type: object
required: ["notifications"]
required:
- notifications
properties:
next_token:
type: string
@ -96,7 +72,12 @@ paths:
type: array
items:
type: object
required: ["actions", "event", "read", "room_id", "ts"]
required:
- actions
- event
- read
- room_id
- ts
title: Notification
properties:
actions:
@ -105,14 +86,14 @@ paths:
The action(s) to perform when the conditions for this rule are met.
See [Push Rules: API](/client-server-api/#push-rules-api).
items:
type:
- object
- string
oneOf:
- type: object
- type: string
event:
title: Event
description: The Event object for the event that triggered the notification.
allOf:
- "$ref": "definitions/client_event_without_room_id.yaml"
- $ref: definitions/client_event_without_room_id.yaml
profile_tag:
type: string
description: The profile tag of the rule that matched this event.
@ -131,5 +112,39 @@ paths:
The unix timestamp at which the event notification was sent,
in milliseconds.
description: The list of events that triggered notifications.
examples:
response:
value: {
"next_token": "abcdef",
"notifications": [
{
"actions": [
"notify"
],
"profile_tag": "hcbvkzxhcvb",
"read": true,
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
}
]
}
tags:
- Push notifications
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

347
data/api/client-server/old_sync.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Sync API
version: 1.0.0
paths:
"/events":
/events:
get:
summary: Listen on the event stream.
description: |-
@ -43,30 +32,26 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: from
description: |-
The token to stream from. This token is either from a previous
request to this API or from the initial sync API.
required: false
x-example: "s3456_9_0"
example: s3456_9_0
schema:
type: string
- in: query
type: integer
name: timeout
description: The maximum time in milliseconds to wait for an event.
required: false
x-example: "35000"
example: "35000"
schema:
type: integer
responses:
200:
description: "The events received, which may be none."
examples:
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
]
}
"200":
description: The events received, which may be none.
content:
application/json:
schema:
type: object
properties:
@ -82,15 +67,26 @@ paths:
token should be used in the next request to `/events`.
chunk:
type: array
description: "An array of events."
description: An array of events.
items:
$ref: "definitions/client_event.yaml"
400:
description: "Bad pagination `from` parameter."
$ref: definitions/client_event.yaml
examples:
response:
value: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
"400":
description: Bad pagination `from` parameter.
tags:
- Room participation
deprecated: true
"/initialSync":
/initialSync:
get:
summary: Get the user's current state.
description: |-
@ -106,13 +102,13 @@ paths:
- accessToken: []
parameters:
- in: query
type: integer
name: limit
description: The maximum number of messages to return for each room.
required: false
x-example: "2"
example: "2"
schema:
type: integer
- in: query
type: boolean
name: archived
description: |-
Whether to include rooms that the user has left. If `false` then
@ -120,15 +116,133 @@ paths:
included. If set to `true` then rooms that the user has left are
included as well. By default this is `false`.
required: false
x-example: "true"
example: "true"
schema:
type: boolean
responses:
200:
"200":
description: The user's current state.
content:
application/json:
schema:
type: object
properties:
end:
type: string
description: |-
A token which correlates to the end of the timelines returned. This
token should be used with the `/events` endpoint to listen for new
events.
presence:
type: array
description: A list of presence events.
items:
$ref: definitions/client_event.yaml
rooms:
type: array
items:
type: object
title: RoomInfo
properties:
room_id:
type: string
description: The ID of this room.
membership:
type: string
description: The user's membership state in this room.
enum:
- invite
- join
- leave
- ban
invite:
type: object
title: InviteEvent
description: The invite event if `membership` is `invite`
allOf:
- $ref: definitions/client_event.yaml
messages:
type: object
title: PaginationChunk
description: The pagination chunk for this room.
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`.
Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve earlier events.
If no earlier events are available, this property may be omitted from
the response.
end:
type: string
description: |-
A token which correlates to the end of `chunk`.
Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
If the user is a member of the room this will be a
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceded them leaving. This array
will consist of at most `limit` elements.
items:
$ref: definitions/client_event.yaml
required:
- end
- chunk
state:
type: array
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the
user has left the room this will be the state of the
room when they left it.
items:
$ref: definitions/client_event.yaml
visibility:
type: string
enum:
- private
- public
description: |-
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array
description: |-
The private data that this user has attached to
this room.
items:
$ref: definitions/client_event.yaml
required:
- room_id
- membership
account_data:
type: array
description: The global private data created by this user.
items:
title: Event
type: object
allOf:
- $ref: ../../event-schemas/schema/core-event-schema/event.yaml
required:
- end
- rooms
- presence
examples:
application/json: {
response:
value: {
"end": "s3456_9_0",
"presence": [
{"$ref": "../../event-schemas/examples/m.presence.yaml"}
{
"$ref": "../../event-schemas/examples/m.presence.yaml"
}
],
"account_data": [
{
@ -178,7 +292,13 @@ paths:
"account_data": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
"content": {
"tags": {
"work": {
"order": 1
}
}
}
},
{
"type": "org.example.custom.room.config",
@ -190,106 +310,7 @@ paths:
}
]
}
schema:
type: object
properties:
end:
type: string
description: |-
A token which correlates to the end of the timelines returned. This
token should be used with the `/events` endpoint to listen for new
events.
presence:
type: array
description: A list of presence events.
items:
$ref: "definitions/client_event.yaml"
rooms:
type: array
items:
type: object
title: RoomInfo
properties:
room_id:
type: string
description: "The ID of this room."
membership:
type: string
description: "The user's membership state in this room."
enum: ["invite", "join", "leave", "ban"]
invite:
type: object
title: "InviteEvent"
description: "The invite event if `membership` is `invite`"
allOf:
- $ref: "definitions/client_event.yaml"
messages:
type: object
title: PaginationChunk
description: "The pagination chunk for this room."
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`.
Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve earlier events.
If no earlier events are available, this property may be omitted from
the response.
end:
type: string
description: |-
A token which correlates to the end of `chunk`.
Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
If the user is a member of the room this will be a
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceded them leaving. This array
will consist of at most `limit` elements.
items:
$ref: "definitions/client_event.yaml"
required: ["end", "chunk"]
state:
type: array
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the
user has left the room this will be the state of the
room when they left it.
items:
$ref: "definitions/client_event.yaml"
visibility:
type: string
enum: ["private", "public"]
description: |-
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array
description: |-
The private data that this user has attached to
this room.
items:
$ref: "definitions/client_event.yaml"
required: ["room_id", "membership"]
account_data:
type: array
description: |-
The global private data created by this user.
items:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["end", "rooms", "presence"]
404:
"404":
description: There is no avatar URL for this user or this user does not exist.
tags:
- Room participation
@ -310,20 +331,42 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: eventId
description: The event ID to get.
required: true
x-example: "$asfDuShaf7Gafaw:matrix.org"
responses:
200:
description: The full event.
examples:
application/json: {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
example: $asfDuShaf7Gafaw:matrix.org
schema:
$ref: "definitions/client_event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
type: string
responses:
"200":
description: The full event.
content:
application/json:
schema:
$ref: definitions/client_event.yaml
examples:
response:
value: {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
"404":
description: The event was not found or you do not have permission to read this
event.
tags:
- Room participation
deprecated: true
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

65
data/api/client-server/openid.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server OpenID API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server OpenID API
version: 1.0.0
paths:
"/user/{userId}/openid/request_token":
post:
@ -44,40 +33,62 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: |-
The user to request an OpenID token for. Should be the user who
is authenticated for the request.
required: true
x-example: "@alice:example.com"
- in: body
name: body
description: An empty object. Reserved for future expansion.
required: true
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {}
description: An empty object. Reserved for future expansion.
required: true
responses:
200:
"200":
description: |-
OpenID token information. This response is nearly compatible with the
response documented in the
[OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)
with the only difference being the lack of an `id_token`. Instead,
the Matrix homeserver's name is provided.
content:
application/json:
schema:
$ref: definitions/openid_token.yaml
examples:
application/json: {
response:
value: {
"access_token": "SomeT0kenHere",
"token_type": "Bearer",
"matrix_server_name": "example.com",
"expires_in": 3600,
"expires_in": 3600
}
schema:
$ref: "definitions/openid_token.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- OpenID
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

87
data/api/client-server/peeking_events.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Sync Guest API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Sync Guest API
version: 1.0.0
paths:
# With an extra " " to disambiguate from the getEvents endpoint
# The extra space makes it sort first for what I'm sure is a good reason.
@ -48,40 +37,33 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: from
description: |-
The token to stream from. This token is either from a previous
request to this API or from the initial sync API.
required: false
x-example: "s3456_9_0"
example: s3456_9_0
schema:
type: string
- in: query
type: integer
name: timeout
description: The maximum time in milliseconds to wait for an event.
required: false
x-example: "35000"
example: "35000"
schema:
type: integer
- in: query
type: string
name: room_id
description: |-
The room ID for which events should be returned.
x-example:
description: The room ID for which events should be returned.
example:
- "!somewhere:over.the.rainbow"
schema:
type: string
responses:
200:
description: "The events received, which may be none."
examples:
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"room_id": "!somewhere:over.the.rainbow",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
"200":
description: The events received, which may be none.
content:
application/json:
schema:
type: object
properties:
@ -97,13 +79,40 @@ paths:
token should be used in the next request to `/events`.
chunk:
type: array
description: "An array of events."
description: An array of events.
items:
type: object
title: Event
allOf:
- "$ref": "definitions/client_event.yaml"
400:
description: "Bad pagination `from` parameter."
- $ref: definitions/client_event.yaml
examples:
response:
value: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"room_id": "!somewhere:over.the.rainbow",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
"400":
description: Bad pagination `from` parameter.
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

130
data/api/client-server/presence.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Presence API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Presence API
version: 1.0.0
paths:
"/presence/{userId}/status":
put:
@ -40,15 +29,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user whose presence state to update.
required: true
x-example: "@alice:example.com"
- in: body
name: presenceState
description: The updated presence state.
required: true
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -58,54 +47,64 @@ paths:
properties:
presence:
type: string
enum: ["online", "offline", "unavailable"]
enum:
- online
- offline
- unavailable
description: The new presence state.
status_msg:
type: string
description: The status message to attach to this state.
required: ["presence"]
required:
- presence
description: The updated presence state.
required: true
responses:
200:
"200":
description: The new presence state was set.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Presence
get:
summary: Get this user's presence state.
description: |-
Get the given user's presence state.
description: Get the given user's presence state.
operationId: getPresence
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user whose presence state to get.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"200":
description: The presence state for this user.
examples:
application/json: {
"presence": "unavailable",
"last_active_ago": 420845
}
content:
application/json:
schema:
type: object
properties:
presence:
type: string
enum: ["online", "offline", "unavailable"]
enum:
- online
- offline
- unavailable
description: This user's presence.
last_active_ago:
type: integer
@ -113,26 +112,53 @@ paths:
The length of time in milliseconds since an action was performed
by this user.
status_msg:
type: [string, "null"]
description: The state message for this user if one was set.
type: ["string", "null"]
currently_active:
type: boolean
description: "Whether the user is currently active"
required: ["presence"]
404:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: You are not allowed to see this user's presence status.
description: Whether the user is currently active
required:
- presence
examples:
application/json: {
response:
value: {
"presence": "unavailable",
"last_active_ago": 420845
}
"403":
description: You are not allowed to see this user's presence status.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to see their presence"
}
"404":
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
tags:
- Presence
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

186
data/api/client-server/profile.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Profile API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Profile API
version: 1.0.0
paths:
"/profile/{userId}/displayname":
put:
@ -38,15 +27,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user whose display name to set.
required: true
x-example: "@alice:example.com"
- in: body
name: displayName
description: The new display name information.
required: true
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -56,18 +45,24 @@ paths:
displayname:
type: string
description: The new display name for this user.
description: The new display name information.
required: true
responses:
200:
"200":
description: The display name was set.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- User data
get:
@ -79,25 +74,30 @@ paths:
operationId: getDisplayName
parameters:
- in: path
type: string
name: userId
description: The user whose display name to get.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"200":
description: The display name for this user.
examples:
application/json: {
"displayname": "Alice Margatroid"
}
content:
application/json:
schema:
type: object
properties:
displayname:
type: string
description: The user's display name if they have set one, otherwise not present.
404:
description: The user's display name if they have set one, otherwise not
present.
examples:
response:
value: {
"displayname": "Alice Margatroid"
}
"404":
description: There is no display name for this user or this user does not exist.
tags:
- User data
@ -112,15 +112,15 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user whose avatar URL to set.
required: true
x-example: "@alice:example.com"
- in: body
name: avatar_url
description: The new avatar information.
required: true
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -131,18 +131,24 @@ paths:
type: string
format: uri
description: The new avatar URL for this user.
description: The new avatar information.
required: true
responses:
200:
"200":
description: The avatar URL was set.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- User data
get:
@ -154,18 +160,17 @@ paths:
operationId: getAvatarUrl
parameters:
- in: path
type: string
name: userId
description: The user whose avatar URL to get.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"200":
description: The avatar URL for this user.
examples:
application/json: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
content:
application/json:
schema:
type: object
properties:
@ -173,7 +178,12 @@ paths:
type: string
format: uri
description: The user's avatar URL if they have set one, otherwise not present.
404:
examples:
response:
value: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
"404":
description: There is no avatar URL for this user or this user does not exist.
tags:
- User data
@ -188,19 +198,17 @@ paths:
operationId: getUserProfile
parameters:
- in: path
type: string
name: userId
description: The user whose profile information to get.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"200":
description: The profile information for this user.
examples:
application/json: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid"
}
content:
application/json:
schema:
type: object
properties:
@ -210,25 +218,55 @@ paths:
description: The user's avatar URL if they have set one, otherwise not present.
displayname:
type: string
description: The user's display name if they have set one, otherwise not present.
403:
x-addedInMatrixVersion: "1.2"
description: The server is unwilling to disclose whether the user exists and/or has profile information.
description: The user's display name if they have set one, otherwise not
present.
examples:
application/json: {
response:
value: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid"
}
"403":
x-addedInMatrixVersion: "1.2"
description: The server is unwilling to disclose whether the user exists and/or
has profile information.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Profile lookup over federation is disabled on this homeserver"
}
"404":
description: There is no profile information for this user or this user does not
exist.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: There is no profile information for this user or this user does not exist.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Profile not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

130
data/api/client-server/pusher.yaml
View file

@ -12,58 +12,30 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Push API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Push API
version: 1.0.0
paths:
"/pushers":
/pushers:
get:
summary: Gets the current pushers for the authenticated user
description: |-
Gets all currently active pushers for the authenticated user.
description: Gets all currently active pushers for the authenticated user.
operationId: getPushers
security:
- accessToken: []
responses:
200:
"200":
description: The pushers for this user.
examples:
application/json: {
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
}
]
}
content:
application/json:
schema:
type: object
properties:
pushers:
type: array
title: Pushers
description: |-
An array containing the current pushers for the user
description: An array containing the current pushers for the user
items:
type: object
title: Pusher
@ -130,9 +102,27 @@ paths:
- device_display_name
- lang
- data
examples:
response:
value: {
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
}
]
}
tags:
- Push notifications
"/pushers/set":
/pushers/set:
post:
summary: Modify a pusher for this user on the homeserver.
description: |-
@ -147,11 +137,9 @@ paths:
operationId: postPusher
security:
- accessToken: []
parameters:
- in: body
name: pusher
description: The pusher information.
required: true
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -182,13 +170,11 @@ paths:
If the `kind` is `"email"`, this is the email address to
send notifications to.
kind:
type:
- "string"
- "null"
description: |-
The kind of pusher to configure. `"http"` makes a pusher that
sends HTTP pokes. `"email"` makes a pusher that emails the
user with unread notifications. `null` deletes the pusher.
type: ["string", "null"]
app_id:
type: string
description: |-
@ -234,7 +220,7 @@ paths:
Required if `kind` is `http`. The URL to use to send
notifications to. MUST be an HTTPS URL with a path of
`/_matrix/push/v1/notify`.
example: "https://push-gateway.location.here/_matrix/push/v1/notify"
example: https://push-gateway.location.here/_matrix/push/v1/notify
format:
type: string
description: |-
@ -251,27 +237,55 @@ paths:
different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different
users. The default is `false`.
required: ['kind', 'app_id', 'pushkey']
required:
- kind
- app_id
- pushkey
description: The pusher information.
required: true
responses:
200:
"200":
description: The pusher was set.
examples:
application/json: {}
content:
application/json:
schema:
type: object
description: An empty object.
400:
description: One or more of the pusher values were invalid.
examples:
application/json: {
response:
value: {}
"400":
description: One or more of the pusher values were invalid.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Push notifications
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

542
data/api/client-server/pushrules.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Push Rules API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Push Rules API
version: 1.0.0
paths:
"/pushrules/":
/pushrules/:
get:
summary: Retrieve all push rulesets.
description: |-
@ -39,21 +28,24 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: All the push rulesets for this user.
content:
application/json:
schema:
type: object
required: ["global"]
required:
- global
properties:
global:
type: object
description: The global ruleset.
title: Ruleset
allOf: [
"$ref": "definitions/push_ruleset.yaml"
]
allOf:
- $ref: definitions/push_ruleset.yaml
examples:
application/json: {
response:
value: {
"global": {
"content": [
{
@ -247,113 +239,133 @@ paths:
"/pushrules/{scope}/{kind}/{ruleId}":
get:
summary: Retrieve a push rule.
description: |-
Retrieve a single specified push rule.
description: Retrieve a single specified push rule.
operationId: getPushRule
security:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
`global` to specify global rules.
- in: path
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: content
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: "nocake"
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
200:
"200":
description: |-
The specific push rule. This will also include keys specific to the
rule itself such as the rule's `actions` and `conditions` if set.
content:
application/json:
schema:
type: object
description: The push rule.
allOf:
- $ref: definitions/push_rule.yaml
examples:
application/json: {
response:
value: {
"actions": [],
"pattern": "cake*lie",
"rule_id": "nocake",
"enabled": true,
"default": false
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
type: object
description: The push rule.
allOf: [
"$ref": "definitions/push_rule.yaml"
]
404:
description: |-
The push rule does not exist.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
delete:
summary: Delete a push rule.
description: |-
This endpoint removes the push rule defined in the path.
description: This endpoint removes the push rule defined in the path.
operationId: deletePushRule
security:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
`global` to specify global rules.
- in: path
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: content
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: "nocake"
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
200:
"200":
description: The push rule was deleted.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
404:
description: |-
The push rule does not exist.
examples:
application/json: {
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
put:
@ -380,68 +392,75 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
`global` to specify global rules.
- in: path
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: content
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: "nocake"
description: |
The identifier for the rule. If the string starts with a dot ("."),
the request MUST be rejected as this is reserved for server-default
rules. Slashes ("/") and backslashes ("\\") are also not allowed.
- in: query
example: nocake
schema:
type: string
- in: query
name: before
required: false
x-example: someRuleId
description: |-
Use 'before' with a `rule_id` as its value to make the new rule the
next-most important rule with respect to the given user defined rule.
It is not possible to add a rule relative to a predefined server rule.
- in: query
example: someRuleId
schema:
type: string
- in: query
name: after
required: false
x-example: anotherRuleId
description: |-
This makes the new rule the next-less important rule relative to the
given user defined rule. It is not possible to add a rule relative
to a predefined server rule.
- in: body
name: pushrule
description: |-
The push rule data. Additional top-level keys may be present depending
on the parameters for the rule `kind`.
required: true
example: anotherRuleId
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"pattern": "cake*lie",
"actions": ["notify"]
"actions": [
"notify"
]
}
properties:
actions:
type: array
description: |-
The action(s) to perform when the conditions for this rule are met.
description: The action(s) to perform when the conditions for this rule are met.
items:
type:
- string
- object
oneOf:
- type: string
- type: object
conditions:
type: array
description: |-
@ -450,210 +469,253 @@ paths:
always matches. Only applicable to `underride` and `override` rules.
items:
type: object
allOf: [ "$ref": "definitions/push_condition.yaml" ]
allOf:
- $ref: definitions/push_condition.yaml
pattern:
type: string
description: Only applicable to `content` rules. The glob-style pattern to match
against.
required:
- actions
description: |-
Only applicable to `content` rules. The glob-style pattern to match against.
required: ["actions"]
The push rule data. Additional top-level keys may be present depending
on the parameters for the rule `kind`.
required: true
responses:
200:
"200":
description: The push rule was created/updated.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
400:
description: There was a problem configuring this push rule.
examples:
application/json: {
response:
value: {}
"400":
description: There was a problem configuring this push rule.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"error": "before/after rule not found: someRuleId",
"errcode": "M_UNKNOWN"
}
"404":
description: The push rule does not exist (when updating a push rule).
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: |-
The push rule does not exist (when updating a push rule).
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
get:
summary: "Get whether a push rule is enabled"
description:
This endpoint gets whether the specified push rule is enabled.
summary: Get whether a push rule is enabled
description: This endpoint gets whether the specified push rule is enabled.
operationId: isPushRuleEnabled
security:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
- in: path
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: cake
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: cake
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: nocake
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
200:
"200":
description: Whether the push rule is enabled.
examples:
application/json: {
"enabled": true
}
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
404:
description: |-
The push rule does not exist.
required:
- enabled
examples:
application/json: {
response:
value: {
"enabled": true
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
put:
summary: "Enable or disable a push rule."
description: |-
This endpoint allows clients to enable or disable the specified push rule.
summary: Enable or disable a push rule.
description: This endpoint allows clients to enable or disable the specified
push rule.
operationId: setPushRuleEnabled
security:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
`global` to specify global rules.
- in: path
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: content
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: "nocake"
description: |
The identifier for the rule.
- in: body
name: body
description: |
Whether the push rule is enabled or not.
required: true
example: nocake
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
required:
- enabled
example: {
"enabled": true
}
description: |
Whether the push rule is enabled or not.
required: true
responses:
200:
"200":
description: The push rule was enabled or disabled.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
404:
description: |-
The push rule does not exist.
examples:
application/json: {
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/actions":
get:
summary: "The actions for a push rule"
description:
This endpoint get the actions for the specified push rule.
summary: The actions for a push rule
description: This endpoint get the actions for the specified push rule.
operationId: getPushRuleActions
security:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
- in: path
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: content
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: nocake
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
200:
"200":
description: The actions for this push rule.
examples:
application/json: {
"actions": [
"notify",
{"set_tweak": "sound", "value": "bing"}
]
}
content:
application/json:
schema:
type: object
properties:
@ -661,24 +723,38 @@ paths:
type: array
description: The action(s) to perform for this rule.
items:
type:
- string
- object
required: ["actions"]
404:
description: |-
The push rule does not exist.
oneOf:
- type: string
- type: object
required:
- actions
examples:
application/json: {
response:
value: {
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "bing"
}
]
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
put:
summary: "Set the actions for a push rule."
summary: Set the actions for a push rule.
description: |-
This endpoint allows clients to change the actions of a push rule.
This can be used to change the actions of builtin rules.
@ -687,32 +763,37 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: scope
required: true
x-example: "global"
description: |-
`global` to specify global rules.
- in: path
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
x-example: room
enum: ["override", "underride", "sender", "room", "content"]
description: |
The kind of rule
- in: path
example: room
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
x-example: "#spam:example.com"
description: |
The identifier for the rule.
- in: body
name: body
description: |
The action(s) to perform when the conditions for this rule are met.
required: true
example: "#spam:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -720,33 +801,58 @@ paths:
type: array
description: The action(s) to perform for this rule.
items:
type:
- string
- object
required: ["actions"]
oneOf:
- type: string
- type: object
required:
- actions
example: {
"actions": [
"notify",
{"set_tweak": "highlight"}
{
"set_tweak": "highlight"
}
]
}
description: |
The action(s) to perform when the conditions for this rule are met.
required: true
responses:
200:
"200":
description: The actions for the push rule were set.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
404:
description: |-
The push rule does not exist.
examples:
application/json: {
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Push notifications
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

73
data/api/client-server/read_markers.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Read Marker API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Read Marker API
version: 1.0.0
paths:
"/rooms/{roomId}/read_markers":
post:
@ -39,52 +28,72 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID to set the read marker in for the user.
required: true
x-example: "!somewhere:example.org"
- in: body
name: body
description: The read marker and optional read receipt locations.
required: true
example: "!somewhere:example.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
"m.fully_read":
m.fully_read:
type: string
description: |-
The event ID the read marker should be located at. The
event MUST belong to the room.
example: "$somewhere:example.org"
example: $somewhere:example.org
x-changedInMatrixVersion:
1.4: |
"1.4": |
This property is no longer required.
"m.read":
m.read:
type: string
description: |-
The event ID to set the read receipt location at. This is
equivalent to calling `/receipt/m.read/$elsewhere:example.org`
and is provided here to save that extra call.
example: "$elsewhere:example.org"
"m.read.private":
example: $elsewhere:example.org
m.read.private:
x-addedInMatrixVersion: "1.4"
type: string
description: |-
The event ID to set the *private* read receipt location at. This
equivalent to calling `/receipt/m.read.private/$elsewhere:example.org`
and is provided here to save that extra call.
example: "$elsewhere:example.org"
example: $elsewhere:example.org
description: The read marker and optional read receipt locations.
required: true
responses:
200:
description: |-
The read marker, and read receipt(s) if provided, have been updated.
"200":
description: The read marker, and read receipt(s) if provided, have been updated.
content:
application/json:
schema:
type: object
properties: {}
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Read Markers
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

96
data/api/client-server/receipts.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Receipts API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Receipts API
version: 1.0.0
paths:
"/rooms/{roomId}/receipt/{receiptType}/{eventId}":
post:
@ -39,13 +28,13 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room in which to send the event.
required: true
x-example: "!wefuh21ffskfuh345:example.com"
- in: path
example: "!wefuh21ffskfuh345:example.com"
schema:
type: string
- in: path
name: receiptType
description: |-
The type of receipt to send. This can also be `m.fully_read` as an
@ -55,23 +44,26 @@ paths:
effectively calls `/read_markers` internally when presented with a receipt
type of `m.fully_read`.
required: true
x-example: "m.read"
x-changedInMatrixVersion:
1.4: |
"1.4": |
Allow `m.read.private` receipts and `m.fully_read` markers to be set.
enum: ["m.read", "m.read.private", "m.fully_read"]
- in: path
example: m.read
schema:
type: string
enum:
- m.read
- m.read.private
- m.fully_read
- in: path
name: eventId
description: The event ID to acknowledge up to.
required: true
x-example: "$1924376522eioj:example.com"
- in: body
name: receipt
description: |-
Extra receipt information to attach to `content` if any. The
server will automatically set the `ts` field.
required: true
example: $1924376522eioj:example.com
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -86,32 +78,58 @@ paths:
example: {
"thread_id": "main"
}
description: |-
Extra receipt information to attach to `content` if any. The
server will automatically set the `ts` field.
required: true
responses:
200:
"200":
description: The receipt was sent.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
maxProperties: 0 # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
400:
examples:
response:
value: {}
"400":
description: |-
The `thread_id` is invalid in some way. For example:
* It is not a string.
* It is empty.
* It is provided for an incompatible receipt type.
* The `event_id` is not related to the `thread_id`.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "thread_id field must be a non-empty string"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

72
data/api/client-server/redaction.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server message redaction API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server message redaction API
version: 1.0.0
paths:
"/rooms/{roomId}/redact/{eventId}/{txnId}":
put:
@ -47,28 +36,31 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room from which to redact the event.
required: true
x-example: "!637q39766251:example.com"
- in: path
example: "!637q39766251:example.com"
schema:
type: string
- in: path
name: eventId
description: The ID of the event to redact
required: true
x-example: "bai2b1i9:matrix.org"
example: bai2b1i9:matrix.org
schema:
type: string
- in: path
name: txnId
type: string
description: |-
The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a
unique ID; it will be used by the server to ensure idempotency of requests.
required: true
x-example: "37"
- in: body
name: body
required: true
example: "37"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -78,19 +70,37 @@ paths:
reason:
type: string
description: The reason for the event being redacted.
required: true
responses:
200:
description: "An ID for the redaction event."
examples:
application/json: {
"event_id": "$YUwQidLecu:example.com"
}
"200":
description: An ID for the redaction event.
content:
application/json:
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
description: A unique identifier for the event.
examples:
response:
value: {
"event_id": "$YUwQidLecu:example.com"
}
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

77
data/api/client-server/refresh.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
title: Matrix Client-Server Registration and Login API
version: 1.0.0
paths:
"/refresh":
/refresh:
post:
x-addedInMatrixVersion: "1.3"
summary: Refresh an access token
@ -48,10 +39,9 @@ paths:
Application Service identity assertion is disabled for this endpoint.
operationId: refresh
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -63,22 +53,18 @@ paths:
description: The refresh token
required:
- refresh_token
required: true
responses:
200:
"200":
description: A new access token and refresh token were generated.
examples:
application/json: {
"access_token": "a_new_token",
"expires_in_ms": 60000,
"refresh_token": "another_new_token"
}
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
description: |-
The new access token to use.
description: The new access token to use.
refresh_token:
type: string
description: |-
@ -93,18 +79,41 @@ paths:
expire.
required:
- access_token
401:
description: |-
The provided token was unknown, or has already been used.
examples:
application/json: {
response:
value: {
"access_token": "a_new_token",
"expires_in_ms": 60000,
"refresh_token": "another_new_token"
}
"401":
description: The provided token was unknown, or has already been used.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Soft logged out",
"soft_logout": true
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

452
data/api/client-server/registration.yaml
View file

@ -12,21 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
title: Matrix Client-Server Registration API
version: 1.0.0
paths:
"/register":
/register:
post:
summary: Register for an account on this homeserver.
description: |-
@ -73,19 +64,20 @@ paths:
parameters:
- in: query
name: kind
type: string
required: false
description: The kind of account to register. Defaults to `user`.
# swagger-UI overrides the default with the example, so better make the
# example the default.
x-example: user
required: false
default: user
example: user
schema:
type: string
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
- in: body
name: body
required: true
default: user
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -97,7 +89,7 @@ paths:
should be authenticated, but is instead used to
authenticate the `register` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
username:
type: string
description: |-
@ -130,18 +122,14 @@ paths:
example: false
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
description: If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
required: true
responses:
200:
"200":
description: The account has been registered.
examples:
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"device_id": "GHTYAJCE"
}
content:
application/json:
schema:
type: object
properties:
@ -194,8 +182,16 @@ paths:
ID of the registered device. Will be the same as the
corresponding parameter in the request, if one was specified.
Required if the `inhibit_login` option is false.
required: ['user_id']
400:
required:
- user_id
examples:
response:
value: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"device_id": "GHTYAJCE"
}
"400":
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -212,69 +208,72 @@ paths:
performing User-Interactive Authentication, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
$ref: definitions/auth_response.yaml
"403":
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular `kind` of account is not
allowed, or that registration is generally not supported by the homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/register/email/requestToken":
/register/email/requestToken:
post:
summary: Begins the validation process for an email to be used during registration.
summary: Begins the validation process for an email to be used during
registration.
description: |-
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver
should validate the email itself, either by sending a validation email
itself or by using a service it has control over.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
$ref: "definitions/request_email_validation.yaml"
$ref: definitions/request_email_validation.yaml
required: true
responses:
200:
"200":
description: |-
An email has been sent to the specified address. Note that this
may be an email containing the validation token or it may be
informing the user of an error.
content:
application/json:
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
$ref: definitions/request_token_response.yaml
"400":
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -285,48 +284,57 @@ paths:
has an account on the homeserver in question.
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
"403":
description: The homeserver does not permit the address to be bound.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/register/msisdn/requestToken":
/register/msisdn/requestToken:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
summary: Requests a validation token be sent to the given phone number for the
purpose of registering an account
description: |-
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. 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: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
$ref: "definitions/request_msisdn_validation.yaml"
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
200:
"200":
description: |-
An SMS message has been sent to the specified phone number. Note
that this may be an SMS message containing the validation token or
it may be informing the user of an error.
content:
application/json:
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
$ref: definitions/request_token_response.yaml
"400":
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -337,18 +345,33 @@ paths:
has an account on the homeserver in question.
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
"403":
description: The homeserver does not permit the address to be bound.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/account/password":
/account/password:
post:
summary: "Changes a user's password."
summary: Changes a user's password.
description: |-
Changes the password for an account on this homeserver.
@ -366,17 +389,16 @@ paths:
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
new_password:
type: string
description: The new password for the account.
example: "ihatebananas"
example: ihatebananas
logout_devices:
type: boolean
description: |-
@ -387,32 +409,41 @@ paths:
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
required: ["new_password"]
- $ref: definitions/auth_data.yaml
required:
- new_password
required: true
responses:
200:
"200":
description: The password has been changed.
examples:
application/json: {}
content:
application/json:
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
429:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/account/password/email/requestToken":
/account/password/email/requestToken:
post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
summary: Requests a validation token be sent to the given email address for the
purpose of resetting a user's password
description: |-
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
@ -430,46 +461,55 @@ paths:
The homeserver should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
operationId: requestTokenToResetPasswordEmail
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
"200":
description: An email was sent to the given address.
content:
application/json:
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:
$ref: definitions/request_token_response.yaml
"400":
description: |-
The referenced third-party identifier is not recognised by 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.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Email not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/account/password/msisdn/requestToken":
/account/password/msisdn/requestToken:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
summary: Requests a validation token be sent to the given phone number for the
purpose of resetting a user's password.
description: |-
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
@ -487,46 +527,54 @@ paths:
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: requestTokenToResetPasswordMSISDN
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
"200":
description: An SMS message was sent to the given phone number.
content:
application/json:
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:
$ref: definitions/request_token_response.yaml
"400":
description: |-
The referenced third-party identifier is not recognised by 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.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Phone number not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/account/deactivate":
/account/deactivate:
post:
summary: "Deactivate a user's account."
summary: Deactivate a user's account.
description: |-
Deactivate the user's account, removing all ability for the user to
login again.
@ -545,18 +593,17 @@ paths:
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
- $ref: definitions/auth_data.yaml
id_server:
type: string
description: |-
@ -566,18 +613,21 @@ paths:
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: "example.org"
example: example.org
required: true
responses:
200:
"200":
description: The account has been deactivated.
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "success"
- "no-support"
- success
- no-support
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). `success` indicates
@ -587,21 +637,24 @@ paths:
being unable to determine an identity server to unbind from. This
must be `success` if the homeserver has no identifiers to unbind
for the user.
example: "success"
example: success
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
"$ref": "definitions/auth_response.yaml"
429:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/register/available":
/register/available:
get:
summary: Checks to see if a username is available on the server.
description: |-
@ -621,18 +674,17 @@ paths:
parameters:
- in: query
name: username
type: string
x-example: my_cool_localpart
required: true
default: my_cool_localpart
description: The username to check the availability of.
example: my_cool_localpart
schema:
type: string
default: my_cool_localpart
responses:
200:
"200":
description: The username is available
examples:
application/json: {
"available": true
}
content:
application/json:
schema:
type: object
properties:
@ -641,7 +693,12 @@ paths:
description: |-
A flag to indicate that the username is available. This should always
be `true` when the server replies with 200 OK.
400:
examples:
response:
value: {
"available": true
}
"400":
description: |-
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
@ -650,16 +707,33 @@ paths:
* `M_INVALID_USERNAME` : The desired username is not a valid user name.
* `M_EXCLUSIVE` : The desired username is in the exclusive namespace
claimed by an application service.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

67
data/api/client-server/registration_tokens.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Registration Token API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
title: Matrix Client-Server Registration Token API
version: 1.0.0
paths:
"/register/m.login.registration_token/validity":
/register/m.login.registration_token/validity:
get:
x-addedInMatrixVersion: "1.2"
summary: Query if a given registration token is still valid.
@ -40,17 +31,16 @@ paths:
parameters:
- in: query
name: token
type: string
x-example: "fBVFdqVE"
required: true
description: The token to check validity of.
example: fBVFdqVE
schema:
type: string
responses:
200:
"200":
description: The check has a result.
examples:
application/json: {
"valid": true
}
content:
application/json:
schema:
type: object
properties:
@ -60,21 +50,44 @@ paths:
True if the token is still valid, false otherwise. This should
additionally be false if the token is not a recognised token by
the server.
required: ['valid']
403:
required:
- valid
examples:
response:
value: {
"valid": true
}
"403":
description: |-
The homeserver does not permit registration and thus all tokens are
considered invalid.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Registration is not enabled on this homeserver."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1

327
data/api/client-server/relations.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Relations API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Relations API
version: 1.0.0
paths:
"/rooms/{roomId}/relations/{eventId}":
get:
@ -45,19 +34,20 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room containing the parent event.
required: true
x-example: "!636q39766251:matrix.org"
- in: path
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The ID of the parent event whose child events are to be returned.
required: true
x-example: "$asfDuShaf7Gafaw"
- in: query
example: $asfDuShaf7Gafaw
schema:
type: string
- in: query
name: from
description: |-
The pagination token to start returning results from. If not supplied, results
@ -67,9 +57,10 @@ paths:
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
required: false
x-example: "page2_token"
- in: query
example: page2_token
schema:
type: string
- in: query
name: to
description: |-
The pagination token to stop returning results at. If not supplied, results
@ -78,9 +69,10 @@ paths:
Like `from`, this can be a previous token from a prior call to this endpoint
or from `/messages` or `/sync`.
required: false
x-example: "page3_token"
example: page3_token
schema:
type: string
- in: query
type: integer
name: limit
description: |-
The maximum number of results to return in a single `chunk`. The server can
@ -88,10 +80,10 @@ paths:
Similarly, the server should apply a default value when not supplied.
required: false
x-example: 20
example: 20
schema:
type: integer
- in: query
type: string
enum: ["b", "f"]
name: dir
x-addedInMatrixVersion: "1.4"
description: |-
@ -99,41 +91,32 @@ paths:
will be returned in chronological order starting at `from`. If it
is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`.
schema:
type: string
enum:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
200:
"200":
description: |-
The paginated child events which point to the parent. If no events are
pointing to the parent or the pagination yields no results, an empty `chunk`
is returned.
examples:
application/json: {
"chunk": [{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
content:
application/json:
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
title: ChildEventsChunk
type: array
description: |-
The child events of the requested event, ordered topologically most-recent first.
description: The child events of the requested event, ordered topologically
most-recent first.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
@ -144,18 +127,40 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
required: ['chunk']
404:
required:
- chunk
examples:
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}
],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
"404":
description: |-
The parent event was not found or the user does not have permission to read
this event (it might be contained in history that is not accessible to the user).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Event relationships
# The same as above, with added `/{relType}`
@ -178,26 +183,28 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room containing the parent event.
required: true
x-example: "!636q39766251:matrix.org"
- in: path
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The ID of the parent event whose child events are to be returned.
required: true
x-example: "$asfDuShaf7Gafaw"
example: $asfDuShaf7Gafaw
schema:
type: string
- in: path
type: string
name: relType
description: |-
The [relationship type](/client-server-api/#relationship-types) to search for.
description: The [relationship type](/client-server-api/#relationship-types) to
search for.
required: true
x-example: "org.example.my_relation"
- in: query
example: org.example.my_relation
schema:
type: string
- in: query
name: from
description: |-
The pagination token to start returning results from. If not supplied, results
@ -207,9 +214,10 @@ paths:
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
required: false
x-example: "page2_token"
- in: query
example: page2_token
schema:
type: string
- in: query
name: to
description: |-
The pagination token to stop returning results at. If not supplied, results
@ -218,9 +226,10 @@ paths:
Like `from`, this can be a previous token from a prior call to this endpoint
or from `/messages` or `/sync`.
required: false
x-example: "page3_token"
example: page3_token
schema:
type: string
- in: query
type: integer
name: limit
description: |-
The maximum number of results to return in a single `chunk`. The server can
@ -228,10 +237,10 @@ paths:
Similarly, the server should apply a default value when not supplied.
required: false
x-example: 20
example: 20
schema:
type: integer
- in: query
type: string
enum: ["b", "f"]
name: dir
x-addedInMatrixVersion: "1.4"
description: |-
@ -239,35 +248,26 @@ paths:
will be returned in chronological order starting at `from`. If it
is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`.
schema:
type: string
enum:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
200:
"200":
description: |-
The paginated child events which point to the parent. If no events are
pointing to the parent or the pagination yields no results, an empty `chunk`
is returned.
examples:
application/json: {
"chunk": [{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
content:
application/json:
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
title: ChildEventsChunk
type: array
description: |-
The child events of the requested event, ordered topologically
@ -275,7 +275,7 @@ paths:
supplied in the URL.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
@ -286,24 +286,47 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
required: ['chunk']
404:
required:
- chunk
examples:
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}
],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
"404":
description: |-
The parent event was not found or the user does not have permission to read
this event (it might be contained in history that is not accessible to the user).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Event relationships
# The same as above, with added `/{eventType}`
"/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
get:
summary: Get the child events for a given parent event, with a given `relType` and `eventType`.
summary: Get the child events for a given parent event, with a given `relType`
and `eventType`.
description: |-
Retrieve all of the child events for a given parent event which relate to the parent
using the given `relType` and have the given `eventType`.
@ -320,26 +343,28 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room containing the parent event.
required: true
x-example: "!636q39766251:matrix.org"
- in: path
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The ID of the parent event whose child events are to be returned.
required: true
x-example: "$asfDuShaf7Gafaw"
- in: path
example: $asfDuShaf7Gafaw
schema:
type: string
- in: path
name: relType
description: |-
The [relationship type](/client-server-api/#relationship-types) to search for.
description: The [relationship type](/client-server-api/#relationship-types) to
search for.
required: true
x-example: "org.example.my_relation"
- in: path
example: org.example.my_relation
schema:
type: string
- in: path
name: eventType
description: |-
The event type of child events to search for.
@ -347,9 +372,10 @@ paths:
Note that in encrypted rooms this will typically always be `m.room.encrypted`
regardless of the event type contained within the encrypted payload.
required: true
x-example: "m.room.message"
- in: query
example: m.room.message
schema:
type: string
- in: query
name: from
description: |-
The pagination token to start returning results from. If not supplied, results
@ -359,9 +385,10 @@ paths:
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
required: false
x-example: "page2_token"
- in: query
example: page2_token
schema:
type: string
- in: query
name: to
description: |-
The pagination token to stop returning results at. If not supplied, results
@ -370,9 +397,10 @@ paths:
Like `from`, this can be a previous token from a prior call to this endpoint
or from `/messages` or `/sync`.
required: false
x-example: "page3_token"
example: page3_token
schema:
type: string
- in: query
type: integer
name: limit
description: |-
The maximum number of results to return in a single `chunk`. The server can
@ -380,10 +408,10 @@ paths:
Similarly, the server should apply a default value when not supplied.
required: false
x-example: 20
example: 20
schema:
type: integer
- in: query
type: string
enum: ["b", "f"]
name: dir
x-addedInMatrixVersion: "1.4"
description: |-
@ -391,35 +419,26 @@ paths:
will be returned in chronological order starting at `from`. If it
is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`.
schema:
type: string
enum:
- b
- f
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
200:
"200":
description: |-
The paginated child events which point to the parent. If no events are
pointing to the parent or the pagination yields no results, an empty `chunk`
is returned.
examples:
application/json: {
"chunk": [{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
content:
application/json:
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
title: ChildEventsChunk
type: array
description: |-
The child events of the requested event, ordered topologically most-recent
@ -427,7 +446,7 @@ paths:
in the URL.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
@ -438,18 +457,54 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
required: ['chunk']
404:
required:
- chunk
examples:
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
"content": {
"m.relates_to": {
"rel_type": "org.example.my_relation",
"event_id": "$asfDuShaf7Gafaw"
}
}
}
],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
"404":
description: |-
The parent event was not found or the user does not have permission to read
this event (it might be contained in history that is not accessible to the user).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Event relationships
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

56
data/api/client-server/report_content.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Report Content API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Report Content API
version: 1.0.0
paths:
"/rooms/{roomId}/report/{eventId}":
post:
@ -36,20 +25,22 @@ paths:
operationId: reportContent
parameters:
- in: path
type: string
name: roomId
description: The room in which the event being reported is located.
required: true
x-example: "!637q39766251:example.com"
- in: path
example: "!637q39766251:example.com"
schema:
type: string
- in: path
name: eventId
description: The event to report.
required: true
x-example: "$something:example.org"
- in: body
name: body
required: true
example: $something:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -65,14 +56,33 @@ paths:
reason:
type: string
description: The reason the content is being reported. May be blank.
required: true
security:
- accessToken: []
responses:
200:
"200":
description: The event has been reported successfully.
content:
application/json:
schema:
type: object
examples:
application/json: {}
response:
value: {}
tags:
- Reporting content
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

92
data/api/client-server/room_event_by_timestamp.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server events in room by date API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server events in room by date API
version: 1.0.0
paths:
"/rooms/{roomId}/timestamp_to_event":
get:
@ -60,38 +49,43 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room to search
required: true
x-example: "!636q39766251:matrix.org"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: query
type: integer
name: ts
description: |-
The timestamp to search from, as given in milliseconds
since the Unix epoch.
required: true
x-example: 1432684800000
example: 1432684800000
schema:
type: integer
- in: query
type: string
enum: [f, b]
name: dir
description: |-
The direction in which to search. `f` for forwards, `b` for backwards.
description: The direction in which to search. `f` for forwards, `b` for
backwards.
required: true
x-example: f
example: f
schema:
type: string
enum:
- f
- b
responses:
200:
description: |-
An event was found matching the search parameters.
"200":
description: An event was found matching the search parameters.
content:
application/json:
schema:
type: object
properties:
event_id:
type: string
description: |-
The ID of the event found
description: The ID of the event found
origin_server_ts:
type: integer
description: |-
@ -99,25 +93,47 @@ paths:
This makes it easy to do a quick comparison to see if the
`event_id` fetched is too far out of range to be useful for your
use case.
required: ['event_id', 'origin_server_ts']
required:
- event_id
- origin_server_ts
examples:
application/json: {
response:
value: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
404:
description: |-
No event was found.
"404":
description: No event was found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

207
data/api/client-server/room_initial_sync.yaml
View file

@ -1,18 +1,7 @@
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Rooms API
version: 1.0.0
paths:
"/rooms/{roomId}/initialSync":
get:
@ -29,16 +18,95 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get the data.
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
responses:
200:
"200":
description: The current state of the room
content:
application/json:
schema:
title: RoomInfo
type: object
properties:
room_id:
type: string
description: The ID of this room.
membership:
type: string
description: The user's membership state in this room.
enum:
- invite
- join
- leave
- ban
messages:
type: object
title: PaginationChunk
description: The pagination chunk for this room.
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve earlier events.
If no earlier events are available, this property may be omitted from
the response.
end:
type: string
description: |-
A token which correlates to the end of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
If the user is a member of the room this will be a
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceded them leaving. This array
will consist of at most `limit` elements.
items:
$ref: definitions/client_event.yaml
required:
- end
- chunk
state:
type: array
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the
user has left the room this will be the state of the
room when they left it.
items:
$ref: definitions/client_event.yaml
visibility:
type: string
enum:
- private
- public
description: |-
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array
description: The private data that this user has attached to this room.
items:
title: Event
type: object
allOf:
- $ref: ../../event-schemas/schema/core-event-schema/event.yaml
required:
- room_id
examples:
application/json: {
response:
value: {
"membership": "join",
"messages": {
"chunk": [
@ -74,82 +142,37 @@ paths:
}
],
"visibility": "private",
"account_data": [{
"account_data": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": "1"}}}
}]
"content": {
"tags": {
"work": {
"order": "1"
}
schema:
title: RoomInfo
type: object
properties:
room_id:
type: string
description: "The ID of this room."
membership:
type: string
description: "The user's membership state in this room."
enum: ["invite", "join", "leave", "ban"]
messages:
type: object
title: PaginationChunk
description: "The pagination chunk for this room."
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve earlier events.
If no earlier events are available, this property may be omitted from
the response.
end:
type: string
description: |-
A token which correlates to the end of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
If the user is a member of the room this will be a
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceded them leaving. This array
will consist of at most `limit` elements.
items:
"$ref": "definitions/client_event.yaml"
required: ["end", "chunk"]
state:
type: array
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the
user has left the room this will be the state of the
room when they left it.
items:
"$ref": "definitions/client_event.yaml"
visibility:
type: string
enum: ["private", "public"]
description: |-
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array
description: |-
The private data that this user has attached to this room.
items:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["room_id"]
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
}
}
}
]
}
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
tags:
- Room participation
deprecated: true
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

78
data/api/client-server/room_send.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server message event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server message event send API
version: 1.0.0
paths:
"/rooms/{roomId}/send/{eventType}/{txnId}":
put:
@ -44,58 +33,81 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to send the event to.
required: true
x-example: "!636q39766251:example.com"
- in: path
example: "!636q39766251:example.com"
schema:
type: string
- in: path
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.message"
example: m.room.message
schema:
type: string
- in: path
name: txnId
type: string
description: |-
The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
ID unique across requests with the same access token; it will be
used by the server to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
required: true
example: "35"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"msgtype": "m.text",
"body": "hello"
}
required: true
responses:
200:
description: "An ID for the sent event."
examples:
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
"200":
description: An ID for the sent event.
content:
application/json:
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
description: A unique identifier for the event.
required:
- event_id
400:
examples:
response:
value: {
"event_id": "$YUwRidLecu:example.com"
}
"400":
description: |-
The request is invalid. A [standard error response](/client-server-api/#standard-error-response)
will be returned. As well as the normal common error codes, other reasons for rejection include:
- `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations).
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

99
data/api/client-server/room_state.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server state event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server state event send API
version: 1.0.0
paths:
"/rooms/{roomId}/state/{eventType}/{stateKey}":
put:
@ -53,28 +42,31 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
- in: path
example: "!636q39766251:example.com"
schema:
type: string
- in: path
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.member"
- in: path
example: m.room.member
schema:
type: string
- in: path
name: stateKey
description: |-
The state_key for the state to send. Defaults to the empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: "@alice:example.com"
- in: body
name: body
required: true
example: "@alice:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -82,33 +74,26 @@ paths:
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
required: true
responses:
200:
description: "An ID for the sent event."
examples:
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
"200":
description: An ID for the sent event.
content:
application/json:
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
description: A unique identifier for the event.
required:
- event_id
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
response:
value: {
"event_id": "$YUwRidLecu:example.com"
}
400:
"400":
description: |-
The sender's request is malformed.
@ -119,12 +104,42 @@ paths:
* `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event
do not point to the room ID for which the state event is to be sent to.
content:
application/json:
schema:
$ref: "definitions/errors/error.yaml"
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_BAD_ALIAS",
"error": "The alias '#hello:example.org' does not point to this room."
}
"403":
description: The sender doesn't have permission to send the event into the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

95
data/api/client-server/room_upgrades.yaml
View file

@ -11,82 +11,99 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Upgrades API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Upgrades API
version: 1.0.0
paths:
"/rooms/{roomId}/upgrade":
post:
summary: Upgrades a room to a new room version.
description: |-
Upgrades the given room to a particular room version.
description: Upgrades the given room to a particular room version.
operationId: upgradeRoom
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
required: true
description: The ID of the room to upgrade.
x-example: "!oldroom:example.org"
- in: body
name: body
required: true
example: "!oldroom:example.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_version:
type: string
description: The new version for the room.
example: {"new_version": "2"}
required: [new_version]
responses:
200:
description: The room was successfully upgraded.
examples:
application/json: {
"replacement_room": "!newroom:example.org"
example: {
"new_version": "2"
}
required:
- new_version
required: true
responses:
"200":
description: The room was successfully upgraded.
content:
application/json:
schema:
type: object
properties:
replacement_room:
type: string
description: The ID of the new room.
required: [replacement_room]
400:
required:
- replacement_room
examples:
response:
value: {
"replacement_room": "!newroom:example.org"
}
"400":
description: |-
The request was invalid. One way this can happen is if the room version
requested is not supported by the homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_UNSUPPORTED_ROOM_VERSION",
"error": "This server does not support that room version"
}
"403":
description: The user is not permitted to upgrade the room.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The user is not permitted to upgrade the room.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You cannot upgrade this room"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room upgrades
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

255
data/api/client-server/rooms.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Rooms API
version: 1.0.0
paths:
"/rooms/{roomId}/event/{eventId}":
get:
@ -38,36 +27,45 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room the event is in.
required: true
x-example: "!636q39766251:matrix.org"
- in: path
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The event ID to get.
required: true
x-example: "$asfDuShaf7Gafaw:matrix.org"
example: $asfDuShaf7Gafaw:matrix.org
schema:
type: string
responses:
200:
"200":
description: The full event.
content:
application/json:
schema:
$ref: definitions/client_event.yaml
examples:
application/json: {
response:
value: {
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
"404":
description: The event was not found or you do not have permission to read this
event.
content:
application/json:
schema:
"$ref": "definitions/client_event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}/{stateKey}":
@ -83,61 +81,80 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to look up the state in.
required: true
x-example: "!636q39766251:example.com"
- in: path
example: "!636q39766251:example.com"
schema:
type: string
- in: path
name: eventType
description: The type of state to look up.
required: true
x-example: "m.room.name"
- in: path
example: m.room.name
schema:
type: string
- in: path
name: stateKey
description: |-
The key of the state to look up. Defaults to an empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: ""
example: ""
schema:
type: string
responses:
200:
"200":
description: The content of the state event.
examples:
application/json: {
"name": "Example room name"}
content:
application/json:
schema:
type: object
404:
examples:
response:
value: {
"name": "Example room name"
}
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
"404":
description: The room has no state with the given type or key.
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state":
get:
summary: Get all state events in the current state of a room.
description: |-
Get the state events for the current state of a room.
description: Get the state events for the current state of a room.
operationId: getRoomState
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to look up the state for.
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
responses:
200:
"200":
description: The current state of the room
content:
application/json:
schema:
type: array
title: RoomState
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the user
has left the room then this will be the state of the room
when they left as a list of events.
items:
$ref: definitions/client_event.yaml
examples:
application/json: [
response:
value: [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
@ -155,64 +172,46 @@ paths:
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
]
schema:
type: array
title: RoomState
description: |-
If the user is a member of the room this will be the
current state of the room as a list of events. If the user
has left the room then this will be the state of the room
when they left as a list of events.
items:
$ref: "definitions/client_event.yaml"
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
tags:
- Room participation
"/rooms/{roomId}/members":
get:
summary: Get the m.room.member events for the room.
description:
Get the list of members for this room.
description: Get the list of members for this room.
operationId: getMembersByRoom
parameters:
- in: path
type: string
name: roomId
description: The room to get the member events for.
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
- in: query
name: at
type: string
description: |-
The point in time (pagination token) to return members for in the room.
This token can be obtained from a `prev_batch` token returned for
each room by the sync API. Defaults to the current state of the room,
as determined by the server.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
example: YWxsCgpOb25lLDM1ODcwOA
schema:
type: string
# XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
# filter might be a better alternative.
# See https://github.com/matrix-org/matrix-doc/issues/1337
- in: query
name: membership
type: string
enum:
- join
- invite
- knock
- leave
- ban
description: |-
The kind of membership to filter for. Defaults to no filtering if
unspecified. When specified alongside `not_membership`, the two
parameters create an 'or' condition: either the membership *is*
the same as `membership` **or** *is not* the same as `not_membership`.
x-example: "join"
- in: query
name: not_membership
example: join
schema:
type: string
enum:
- join
@ -220,20 +219,40 @@ paths:
- knock
- leave
- ban
- in: query
name: not_membership
description: |-
The kind of membership to exclude from the results. Defaults to no
filtering if unspecified.
x-example: leave
example: leave
schema:
type: string
enum:
- join
- invite
- knock
- leave
- ban
security:
- accessToken: []
responses:
200:
"200":
description: |-
A list of members of the room. If you are joined to the room then
this will be the current members of the room. If you have left the
room then this will be the members of the room when you left.
content:
application/json:
schema:
type: object
properties:
chunk:
type: array
items:
$ref: definitions/client_event.yaml
examples:
application/json: {
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:example.com",
@ -241,48 +260,36 @@ paths:
}
]
}
schema:
type: object
properties:
chunk:
type: array
items:
$ref: "definitions/client_event.yaml"
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
tags:
- Room participation
"/rooms/{roomId}/joined_members":
get:
summary: Gets the list of currently joined users and their profile data.
description:
This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server.
description: This API returns a map of MXIDs to member info objects for members
of the room. The current user must be in the room for it to work, unless
it is an Application Service in which case any of the AS's users must be
in the room. This API is primarily for Application Services and should
be faster to respond than `/members` as it can be implemented more
efficiently on the server.
operationId: getJoinedMembersByRoom
parameters:
- in: path
type: string
name: roomId
description: The room to get the members of.
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
security:
- accessToken: []
responses:
200:
description: |-
A map of MXID to room member objects.
examples:
application/json: {
"joined": {
"@bar:example.com": {
"display_name": "Bar",
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
}
}
}
"200":
description: A map of MXID to room member objects.
content:
application/json:
schema:
type: object
properties:
@ -297,11 +304,37 @@ paths:
avatar_url:
type: string
format: uri
description: The avatar of the user this object is representing, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris).
description: The avatar of the user this object is representing, as an [`mxc://`
URI](/client-server-api/#matrix-content-mxc-uris).
description: A map from user ID to a RoomMember object.
type: object
403:
description: >
examples:
response:
value: {
"joined": {
"@bar:example.com": {
"display_name": "Bar",
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
}
}
}
"403":
description: |
You aren't a member of the room.
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

138
data/api/client-server/search.yaml
View file

@ -11,41 +11,30 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Search API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Search API
version: 1.0.0
paths:
"/search":
/search:
post:
summary: Perform a server-side search.
description: |-
Performs a full text search across different categories.
description: Performs a full text search across different categories.
operationId: search
security:
- accessToken: []
parameters:
- in: query
name: next_batch
type: string
description: |-
The point to return events from. If given, this should be a
`next_batch` result from a previous call to this endpoint.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
required: true
example: YWxsCgpOb25lLDM1ODcwOA
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -69,9 +58,8 @@ paths:
properties:
search_categories:
type: object
title: "Categories"
description: Describes which categories to search in and
their criteria.
title: Categories
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
@ -85,19 +73,23 @@ paths:
type: array
items:
type: string
enum: ["content.body", "content.name", "content.topic"]
enum:
- content.body
- content.name
- content.topic
description: The keys to search. Defaults to all.
filter:
type: object
title: Filter
description: |-
This takes a [filter](/client-server-api/#filtering).
description: This takes a [filter](/client-server-api/#filtering).
allOf:
- $ref: "definitions/room_event_filter.yaml"
- $ref: definitions/room_event_filter.yaml
order_by:
title: "Ordering"
title: Ordering
type: string
enum: ["recent", "rank"]
enum:
- recent
- rank
description: |-
The order in which to search for results.
By default, this is `"rank"`.
@ -110,19 +102,19 @@ paths:
properties:
before_limit:
type: integer
title: "Before limit"
title: Before limit
description: |-
How many events before the result are
returned. By default, this is `5`.
after_limit:
type: integer
title: "After limit"
title: After limit
description: |-
How many events after the result are
returned. By default, this is `5`.
include_profile:
type: boolean
title: "Return profile information"
title: Return profile information
description: |-
Requests that the server returns the
historic profile information for the users
@ -153,24 +145,30 @@ paths:
key:
type: string
title: Group Key
description: |-
Key that defines the group.
enum: ["room_id", "sender"]
required: ["search_term"]
required: ["search_categories"]
description: Key that defines the group.
enum:
- room_id
- sender
required:
- search_term
required:
- search_categories
required: true
responses:
200:
"200":
description: Results of the search.
content:
application/json:
schema:
type: object
title: Results
required: ["search_categories"]
required:
- search_categories
properties:
search_categories:
type: object
title: Result Categories
description: Describes which categories to search in and
their criteria.
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
@ -183,7 +181,8 @@ paths:
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming which may change the query terms.
description: List of words which should be highlighted, useful for stemming
which may change the query terms.
items:
type: string
results:
@ -197,15 +196,14 @@ paths:
properties:
rank:
type: number
description: A number that describes how closely
this result matches the search. Higher is
closer.
description: A number that describes how closely this result matches the search.
Higher is closer.
result:
type: object
title: Event
description: The event that matched.
allOf:
- "$ref": "definitions/client_event.yaml"
- $ref: definitions/client_event.yaml
context:
type: object
title: Event Context
@ -214,13 +212,11 @@ paths:
start:
type: string
title: Start Token
description: |-
Pagination token for the start of the chunk
description: Pagination token for the start of the chunk
end:
type: string
title: End Token
description: |-
Pagination token for the end of the chunk
description: Pagination token for the end of the chunk
profile_info:
type: object
title: Profile Information
@ -248,7 +244,7 @@ paths:
items:
title: Event
type: object
"$ref": "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
events_after:
type: array
title: Events After
@ -256,7 +252,7 @@ paths:
items:
title: Event
type: object
"$ref": "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
state:
type: object
title: Current state
@ -271,7 +267,7 @@ paths:
type: array
title: Room State
items:
"$ref": "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
groups:
type: object
title: Groups
@ -288,8 +284,7 @@ paths:
additionalProperties:
type: object
title: Group Value
description: |-
The results for a particular group value.
description: The results for a particular group value.
properties:
next_batch:
type: string
@ -308,8 +303,7 @@ paths:
groups.
results:
type: array
description: |-
Which results are in this group.
description: Which results are in this group.
items:
type: string
title: Result Event ID
@ -322,7 +316,8 @@ paths:
the next call. If this field is absent, there are no
more results.
examples:
application/json: {
response:
value: {
"search_categories": {
"room_events": {
"groups": {
@ -355,11 +350,28 @@ paths:
}
}
}
400:
"400":
description: Part of the request was invalid.
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Search
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

201
data/api/client-server/space_hierarchy.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Space Hierarchy API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Space Hierarchy API
version: 1.0.0
paths:
"/rooms/{roomId}/hierarchy":
get:
@ -44,30 +33,32 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID of the space to get a hierarchy for.
required: true
x-example: "!space:example.org"
example: "!space:example.org"
schema:
type: string
- in: query
type: boolean
name: suggested_only
description: |-
Optional (default `false`) flag to indicate whether or not the server should only consider
suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event
contents.
x-example: true
example: true
schema:
type: boolean
- in: query
type: integer
name: limit
description: |-
Optional limit for the maximum number of rooms to include per response. Must be an integer
greater than zero.
Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
x-example: 20
- in: query
example: 20
schema:
type: integer
- in: query
name: max_depth
description: |-
Optional limit for how far to go into the space. Must be a non-negative integer.
@ -75,20 +66,70 @@ paths:
When reached, no further child rooms will be returned.
Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
x-example: 5
example: 5
schema:
type: integer
- in: query
type: string
name: from
description: |-
A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot
be changed from the first request.
x-example: "next_batch_token"
example: next_batch_token
schema:
type: string
responses:
200:
"200":
description: A portion of the space tree, starting at the provided room ID.
content:
application/json:
schema:
type: object
properties:
rooms:
type: array
description: The rooms for the current page, with the current filters.
items:
allOf:
- $ref: definitions/public_rooms_chunk.yaml
- type: object
title: ChildRoomsChunk
properties:
room_type:
type: string
description: The `type` of room (from
[`m.room.create`](/client-server-api/#mroomcreate)),
if any.
children_state:
type: array
description: |-
A portion of the space tree, starting at the provided room ID.
The [`m.space.child`](#mspacechild) events of the space-room, represented
as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key.
If the room is not a space-room, this should be empty.
items:
allOf:
- $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
- type: object
title: StrippedChildStateEvent
properties:
origin_server_ts:
type: integer
format: int64
description: The `origin_server_ts` for the event.
required:
- origin_server_ts
required:
- children_state
next_batch:
type: string
description: |-
A token to supply to `from` to keep paginating the responses. Not present when there are
no further results.
required:
- rooms
examples:
application/json: {
response:
value: {
"rooms": [
{
"room_id": "!space:example.org",
@ -106,7 +147,9 @@ paths:
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": ["example.org"]
"via": [
"example.org"
]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
@ -116,50 +159,24 @@ paths:
],
"next_batch": "next_batch_token"
}
schema:
type: object
properties:
rooms:
type: array
"400":
description: |-
The rooms for the current page, with the current filters.
items:
allOf:
- $ref: "definitions/public_rooms_chunk.yaml"
- type: object
title: ChildRoomsChunk
properties:
# Override x-addedInMatrixVersion for room_type (this endpoint had it first)
room_type:
type: string
description: |-
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
children_state:
type: array
description: |-
The [`m.space.child`](#mspacechild) events of the space-room, represented
as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key.
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
If the room is not a space-room, this should be empty.
items:
allOf:
- $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
- type: object
title: StrippedChildStateEvent
properties:
origin_server_ts:
type: integer
format: int64
description: The `origin_server_ts` for the event.
required: [origin_server_ts]
required: [children_state]
next_batch:
type: string
description: |-
A token to supply to `from` to keep paginating the responses. Not present when there are
no further results.
required: [rooms]
403:
- The `from` token is unknown to the server.
- `suggested_only` or `max_depth` changed during pagination.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "suggested_only and max_depth cannot change on paginated requests"
}
"403":
description: |-
The user cannot view or peek on the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
@ -167,30 +184,36 @@ paths:
- The room is not set up for peeking.
- The user has been banned from the room.
- The room does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to view this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
400:
description: |-
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The `from` token is unknown to the server.
- `suggested_only` or `max_depth` changed during pagination.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "suggested_only and max_depth cannot change on paginated requests"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Spaces
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

46
data/api/client-server/sso_login_redirect.yaml
View file

@ -11,17 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server SSO Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
title: Matrix Client-Server SSO Login API
version: 1.0.0
paths:
"/login/sso/redirect":
/login/sso/redirect:
get:
x-addedInMatrixVersion: "1.1"
summary: Redirect the user's browser to the SSO interface.
@ -35,18 +30,20 @@ paths:
operationId: redirectToSSO
parameters:
- in: query
type: string
name: redirectUrl
description: |-
URI to which the user will be redirected after the homeserver has
authenticated the user with SSO.
required: true
schema:
type: string
responses:
302:
"302":
description: A redirect to the SSO interface.
headers:
Location:
type: "string"
schema:
type: string
tags:
- Session management
"/login/sso/redirect/{idpId}":
@ -63,29 +60,44 @@ paths:
operationId: redirectToIdP
parameters:
- in: path
type: string
name: idpId
required: true
description: |-
The `id` of the IdP from the `m.login.sso` `identity_providers`
array denoting the user's selection.
- in: query
schema:
type: string
- in: query
name: redirectUrl
description: |-
URI to which the user will be redirected after the homeserver has
authenticated the user with SSO.
required: true
schema:
type: string
responses:
302:
"302":
description: A redirect to the SSO interface.
headers:
Location:
type: "string"
404:
schema:
type: string
"404":
description: |-
The IdP ID was not recognized by the server. The server is encouraged
to provide a user-friendly page explaining the error given the user
will be navigated to it.
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

175
data/api/client-server/sync.yaml
View file

@ -11,22 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server sync API
version: 1.0.0
paths:
"/sync":
/sync:
get:
summary: Synchronise the client's state and receive new messages.
description: |-
@ -57,7 +47,6 @@ paths:
parameters:
- in: query
name: filter
type: string
description: |-
The ID of a filter created using the filter API or a filter JSON
object encoded as a string. The server will detect whether it is
@ -68,17 +57,19 @@ paths:
long poll requests.
See [Filtering](/client-server-api/#filtering) for more information.
x-example: "66696p746572"
example: 66696p746572
schema:
type: string
- in: query
name: since
type: string
description: |-
A point in time to continue a sync from. This should be the
`next_batch` token returned by an earlier call to this endpoint.
x-example: "s72594_4483_1934"
example: s72594_4483_1934
schema:
type: string
- in: query
name: full_state
type: boolean
description: |-
Controls whether to include the full state for all rooms the user
is a member of.
@ -93,11 +84,11 @@ paths:
changed since the point indicated by `since` will be returned.
By default, this is `false`.
x-example: "false"
example: "false"
schema:
type: boolean
- in: query
name: set_presence
type: string
enum: ["offline", "online", "unavailable"]
description: |-
Controls whether the client is automatically marked as online by
polling this API. If this parameter is omitted then the client is
@ -105,10 +96,15 @@ paths:
the parameter is set to "offline" then the client is not marked as
being online when it uses this API. When set to "unavailable", the
client is marked as being idle.
x-example: "offline"
example: offline
schema:
type: string
enum:
- offline
- online
- unavailable
- in: query
name: timeout
type: integer
description: |-
The maximum time to wait, in milliseconds, before returning this
request. If no events (or other data) become available before this
@ -116,12 +112,15 @@ paths:
By default, this is `0`, so the server will return immediately
even if the response is empty.
x-example: 30000
example: 30000
schema:
type: integer
responses:
200:
description:
The initial snapshot or delta for the client to use to update their
"200":
description: The initial snapshot or delta for the client to use to update their
state.
content:
application/json:
schema:
type: object
properties:
@ -133,8 +132,7 @@ paths:
rooms:
title: Rooms
type: object
description: |-
Updates to rooms.
description: Updates to rooms.
properties:
join:
title: Joined Rooms
@ -153,7 +151,7 @@ paths:
Information about the room which clients may need to
correctly render it to users.
properties:
"m.heroes":
m.heroes:
type: array
description: |-
The users which can be used to generate a room name
@ -177,14 +175,14 @@ paths:
field may be omitted.
items:
type: string
"m.joined_member_count":
m.joined_member_count:
type: integer
description: |-
The number of users with `membership` of `join`,
including the client's own user ID. If this field has
not changed since the last sync, it may be omitted.
Required otherwise.
"m.invited_member_count":
m.invited_member_count:
type: integer
description: |-
The number of users with `membership` of `invite`.
@ -206,7 +204,7 @@ paths:
required to display the senders of the timeline events
in this response.
allOf:
- $ref: "definitions/state_event_batch.yaml"
- $ref: definitions/state_event_batch.yaml
timeline:
title: Timeline
type: object
@ -214,7 +212,7 @@ paths:
The timeline of messages and state changes in the
room.
allOf:
- $ref: "definitions/timeline_batch.yaml"
- $ref: definitions/timeline_batch.yaml
ephemeral:
title: Ephemeral
type: object
@ -225,7 +223,7 @@ paths:
[typing notification](#typing-notifications) and
[read receipt](#receipts) events.
allOf:
- $ref: "definitions/event_batch.yaml"
- $ref: definitions/event_batch.yaml
account_data:
title: Account Data
type: object
@ -233,7 +231,7 @@ paths:
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
- $ref: definitions/event_batch.yaml
unread_notifications:
title: Unread Notification Counts
type: object
@ -246,20 +244,19 @@ paths:
these counts will only be for the main timeline rather than all events in the room.
See the [threading module](#threading) for more information.
x-changedInMatrixVersion:
1.4: |
"1.4": |
Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
the `RoomEventFilter` for `/sync`.
properties:
highlight_count:
title: Highlighted notification count
type: integer
description: The number of unread notifications
for this room with the highlight flag set.
description: The number of unread notifications for this room with the highlight
flag set.
notification_count:
title: Total notification count
type: integer
description: The total number of unread notifications
for this room.
description: The total number of unread notifications for this room.
unread_thread_notifications:
title: Unread Thread Notification Counts
type: object
@ -278,13 +275,12 @@ paths:
highlight_count:
title: ThreadedHighlightNotificationCount
type: integer
description: |-
The number of unread notifications for this *thread* with the highlight flag set.
description: The number of unread notifications for this *thread* with the
highlight flag set.
notification_count:
title: ThreadedTotalNotificationCount
type: integer
description: |-
The total number of unread notifications for this *thread*.
description: The total number of unread notifications for this *thread*.
invite:
title: Invited Rooms
type: object
@ -303,15 +299,16 @@ paths:
to.
properties:
events:
description: The [stripped state events](#stripped-state) that form the invite state.
description: The [stripped state events](#stripped-state) that form the invite
state.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: array
knock:
title: Knocked rooms
type: object
description: |-
The rooms that the user has knocked upon, mapped as room ID to room information.
description: The rooms that the user has knocked upon, mapped as room ID to room
information.
additionalProperties:
title: Knocked Room
type: object
@ -319,13 +316,14 @@ paths:
knock_state:
title: KnockState
type: object
description: |-
The [stripped state](#stripped-state) of a room that the user has knocked upon.
description: The [stripped state](#stripped-state) of a room that the user has
knocked upon.
properties:
events:
description: The [stripped state events](#stripped-state) that form the knock state.
description: The [stripped state events](#stripped-state) that form the knock
state.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: array
leave:
title: Left rooms
@ -340,10 +338,9 @@ paths:
state:
title: State
type: object
description: |-
The state updates for the room up to the start of the timeline.
description: The state updates for the room up to the start of the timeline.
allOf:
- $ref: "definitions/state_event_batch.yaml"
- $ref: definitions/state_event_batch.yaml
timeline:
title: Timeline
type: object
@ -351,7 +348,7 @@ paths:
The timeline of messages and state changes in the
room up to the point when the user left.
allOf:
- $ref: "definitions/timeline_batch.yaml"
- $ref: definitions/timeline_batch.yaml
account_data:
title: Account Data
type: object
@ -359,21 +356,19 @@ paths:
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
- $ref: definitions/event_batch.yaml
presence:
title: Presence
type: object
description: |-
The updates to the presence status of other users.
description: The updates to the presence status of other users.
allOf:
- $ref: "definitions/event_batch.yaml"
- $ref: definitions/event_batch.yaml
account_data:
title: Account Data
type: object
description: |-
The global private data created by this user.
description: The global private data created by this user.
allOf:
- $ref: "definitions/event_batch.yaml"
- $ref: definitions/event_batch.yaml
to_device:
title: ToDevice
type: object
@ -397,11 +392,14 @@ paths:
required:
- next_batch
examples:
application/json: {
response:
value: {
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{"$ref": "../../event-schemas/examples/m.presence.yaml"}
{
"$ref": "../../event-schemas/examples/m.presence.yaml"
}
]
},
"account_data": {
@ -446,13 +444,19 @@ paths:
},
"ephemeral": {
"events": [
{"$ref": "../../event-schemas/examples/m.typing.yaml"},
{"$ref": "../../event-schemas/examples/m.receipt.yaml"}
{
"$ref": "../../event-schemas/examples/m.typing.yaml"
},
{
"$ref": "../../event-schemas/examples/m.receipt.yaml"
}
]
},
"account_data": {
"events": [
{"$ref": "../../event-schemas/examples/m.tag.yaml"},
{
"$ref": "../../event-schemas/examples/m.tag.yaml"
},
{
"type": "org.example.custom.room.config",
"content": {
@ -481,13 +485,17 @@ paths:
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {"name": "My Room Name"}
"content": {
"name": "My Room Name"
}
},
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "invite"}
"content": {
"membership": "invite"
}
}
]
}
@ -501,13 +509,17 @@ paths:
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {"name": "My Room Name"}
"content": {
"name": "My Room Name"
}
},
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "knock"}
"content": {
"membership": "knock"
}
}
]
}
@ -518,3 +530,18 @@ paths:
}
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

144
data/api/client-server/tags.yaml
View file

@ -12,50 +12,40 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server tag API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server tag API
version: 1.0.0
paths:
"/user/{userId}/rooms/{roomId}/tags":
get:
summary: List the tags for a room.
description: |-
List the tags set by a user on a room.
description: List the tags set by a user on a room.
operationId: getRoomTags
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The id of the user to get tags for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
required: true
description: |-
The ID of the room to get tags for.
x-example: "!726s6s6q:example.com"
description: The ID of the room to get tags for.
example: "!726s6s6q:example.com"
schema:
type: string
responses:
200:
description:
The list of tags for the user for the room.
"200":
description: The list of tags for the user for the room.
content:
application/json:
schema:
type: object
properties:
@ -73,10 +63,15 @@ paths:
position of the room under the given tag.
additionalProperties: true
examples:
application/json: {
response:
value: {
"tags": {
"m.favourite": {"order": 0.1},
"u.Work": {"order": 0.7},
"m.favourite": {
"order": 0.1
},
"u.Work": {
"order": 0.7
},
"u.Customers": {}
}
}
@ -85,39 +80,37 @@ paths:
"/user/{userId}/rooms/{roomId}/tags/{tag}":
put:
summary: Add a tag to a room.
description: |-
Add a tag to the room.
description: Add a tag to the room.
operationId: setRoomTag
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The id of the user to add a tag for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
required: true
description: |-
The ID of the room to add a tag to.
x-example: "!726s6s6q:example.com"
- in: path
description: The ID of the room to add a tag to.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
name: tag
required: true
description: |-
The tag to add.
x-example: "u.work"
- in: body
name: body
required: true
description: |-
Extra data for the tag, e.g. ordering.
description: The tag to add.
example: u.work
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -131,53 +124,74 @@ paths:
example: {
"order": 0.25
}
description: Extra data for the tag, e.g. ordering.
required: true
responses:
200:
description:
The tag was successfully added.
"200":
description: The tag was successfully added.
content:
application/json:
schema:
type: object
examples:
application/json: {}
response:
value: {}
tags:
- User data
delete:
summary: Remove a tag from the room.
description: |-
Remove a tag from the room.
description: Remove a tag from the room.
operationId: deleteRoomTag
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The id of the user to remove a tag for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
required: true
description: |-
The ID of the room to remove a tag from.
x-example: "!726s6s6q:example.com"
- in: path
description: The ID of the room to remove a tag from.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
name: tag
required: true
description: |-
The tag to remove.
x-example: "u.work"
description: The tag to remove.
example: u.work
schema:
type: string
responses:
200:
description:
The tag was successfully removed.
"200":
description: The tag was successfully removed.
content:
application/json:
schema:
type: object
examples:
application/json: {}
response:
value: {}
tags:
- User data
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

179
data/api/client-server/third_party_lookup.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Third-party Lookup API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Third-party Lookup API
version: 1.0.0
paths:
"/thirdparty/protocols":
/thirdparty/protocols:
get:
summary: Retrieve metadata about all protocols that a homeserver supports.
description: |-
@ -38,8 +27,10 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The protocols supported by the homeserver.
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
tags:
@ -47,32 +38,37 @@ paths:
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the homeserver supports.
description: |-
Fetches the metadata from the homeserver about a particular third-party protocol.
description: Fetches the metadata from the homeserver about a particular
third-party protocol.
operationId: getProtocolMetadata
security:
- accessToken: []
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
description: The name of the protocol.
required: true
x-example: "irc"
example: irc
schema:
type: string
responses:
200:
"200":
description: The protocol was found and metadata returned.
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol.yaml
404:
"404":
description: The protocol is unknown.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND"
}
tags:
- Third-party Lookup
"/thirdparty/location/{protocol}":
@ -93,29 +89,36 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: The protocol used to communicate to the third-party network.
required: true
x-example: irc
example: irc
schema:
type: string
- in: query
name: searchFields
type: string
description: |-
One or more custom fields to help identify the third-party
location.
schema:
type: string
responses:
200:
"200":
description: At least one portal room was found.
content:
application/json:
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
"404":
description: No portal rooms were found.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND"
}
tags:
- Third-party Lookup
"/thirdparty/user/{protocol}":
@ -130,32 +133,38 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
description: The name of the protocol.
required: true
x-example: irc
example: irc
schema:
type: string
- in: query
name: fields...
description: One or more custom fields that are passed to the AS to help
identify the user.
schema:
type: string
description: |-
One or more custom fields that are passed to the AS to help identify the user.
responses:
200:
"200":
description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
"404":
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND"
}
tags:
- Third-party Lookup
"/thirdparty/location":
/thirdparty/location:
get:
summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |-
@ -167,54 +176,78 @@ paths:
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
required: true
x-example: "#matrix:matrix.org"
example: "#matrix:matrix.org"
schema:
type: string
responses:
200:
description: |-
All found third-party locations.
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
"404":
description: The Matrix room alias was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND"
}
tags:
- Third-party Lookup
"/thirdparty/user":
/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.
description: Retrieve an array of third-party users from a Matrix User ID.
operationId: queryUserByID
security:
- accessToken: []
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
required: true
x-example: "@bob:matrix.org"
example: "@bob:matrix.org"
schema:
type: string
responses:
200:
description: |-
An array of third-party users.
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
"404":
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND"
}
tags:
- Third-party Lookup
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

85
data/api/client-server/third_party_membership.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Membership API for third-party identifiers"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Membership API for third-party identifiers
version: 1.0.0
paths:
"/rooms/{roomId}/invite":
post:
@ -71,20 +60,20 @@ paths:
If a token is requested from the identity server, the homeserver will
append a `m.room.third_party_invite` event to the room.
operationId: inviteBy3PID
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
example: "!d41d8cd:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -96,7 +85,8 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
@ -111,16 +101,23 @@ paths:
address:
type: string
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
required:
- id_server
- id_access_token
- medium
- address
required: true
responses:
200:
"200":
description: The user has been invited to join the room.
examples:
application/json: {
}
content:
application/json:
schema:
type: object
403:
examples:
response:
value: {}
"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:
@ -128,14 +125,36 @@ paths:
- 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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

130
data/api/client-server/threads_list.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Threads List API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Threads List API
version: 1.0.0
paths:
"/rooms/{roomId}/threads":
get:
@ -41,46 +30,49 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID where the thread roots are located.
required: true
x-example: "!room:example.org"
- in: query
example: "!room:example.org"
schema:
type: string
- in: query
name: include
enum: [all, participated]
description: |-
Optional (default `all`) flag to denote which thread roots are of interest to the caller.
When `all`, all thread roots found in the room are returned. When `participated`, only
thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships)
will be returned.
x-example: "all"
example: all
schema:
type: string
enum:
- all
- participated
- in: query
type: integer
name: limit
description: |-
Optional limit for the maximum number of thread roots to include per response. Must be an integer
greater than zero.
Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
x-example: 20
example: 20
schema:
type: integer
- in: query
type: string
name: from
description: |-
A pagination token from a previous result. When not provided, the server starts paginating from
the most recent event visible to the user (as per history visibility rules; topologically).
x-example: "next_batch_token"
example: next_batch_token
schema:
type: string
responses:
200:
description: |-
A portion of the available thread roots in the room, based on the filter criteria.
examples:
application/json: {
"chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }],
"next_batch": "next_batch_token"
}
"200":
description: A portion of the available thread roots in the room, based on the
filter criteria.
content:
application/json:
schema:
type: object
properties:
@ -94,14 +86,41 @@ paths:
event is returned redacted to the caller. This is to simulate the same behaviour of a client doing
aggregation locally on the thread.
items:
$ref: "definitions/client_event.yaml"
$ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
A token to supply to `from` to keep paginating the responses. Not present when there are
no further results.
required: [chunk]
403:
required:
- chunk
examples:
response:
value: {
"chunk": [
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
],
"next_batch": "next_batch_token"
}
"400":
description: |-
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The `from` token is unknown to the server.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Unknown pagination token"
}
"403":
description: |-
The user cannot view or peek on the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
@ -109,29 +128,36 @@ paths:
- The room is not set up for peeking.
- The user has been banned from the room.
- The room does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to view this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
400:
description: |-
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The `from` token is unknown to the server.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "Unknown pagination token"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Threads
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

76
data/api/client-server/to_device.yaml
View file

@ -11,22 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Send-to-device API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Send-to-device API
version: 1.0.0
paths:
"/sendToDevice/{eventType}/{txnId}":
put:
@ -39,23 +27,25 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.new_device"
example: m.new_device
schema:
type: string
- in: path
name: txnId
type: string
description: |-
The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
ID unique across requests with the same access token; it will be
used by the server to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
required: true
example: "35"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
title: body
@ -72,21 +62,37 @@ paths:
type: object
title: EventContent
description: Message content
example: {
"@alice:example.com": {
"TLLBEANAAG": {
"example_content_key": "value"
}
}
}
required: ["messages"]
example:
"@alice:example.com":
TLLBEANAAG:
example_content_key: value
required:
- messages
required: true
responses:
200:
description:
The message was successfully sent.
examples:
application/json: {}
"200":
description: The message was successfully sent.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
tags:
- Send-to-Device messaging
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

70
data/api/client-server/typing.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Typing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Typing API
version: 1.0.0
paths:
"/rooms/{roomId}/typing/{userId}":
put:
@ -40,21 +29,22 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user who has started to type.
required: true
x-example: "@alice:example.com"
- in: path
example: "@alice:example.com"
schema:
type: string
- in: path
name: roomId
description: The room in which the user is typing.
required: true
x-example: "!wefh3sfukhs:example.com"
- in: body
name: typingState
description: The current typing state.
required: true
example: "!wefh3sfukhs:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -70,18 +60,40 @@ paths:
timeout:
type: integer
description: The length of time in milliseconds to mark this user as typing.
required: ["typing"]
required:
- typing
description: The current typing state.
required: true
responses:
200:
"200":
description: The new typing state was set.
examples:
application/json: {
}
content:
application/json:
schema:
type: object # empty json object
429:
examples:
response:
value: {}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

121
data/api/client-server/users.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server User Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server User Directory API
version: 1.0.0
paths:
"/user_directory/search":
/user_directory/search:
post:
summary: Searches the user directory.
description: |-
@ -44,27 +33,64 @@ paths:
operationId: searchUserDirectory
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
search_term:
type: string
description: The term to search for
example: "foo"
example: foo
limit:
type: integer
description: The maximum number of results to return. Defaults to 10.
example: 10
required: ["search_term"]
required:
- search_term
required: true
responses:
200:
"200":
description: The results of the search.
content:
application/json:
schema:
type: object
required:
- results
- limited
properties:
results:
type: array
description: Ordered by rank and then whether or not profile info is available.
items:
title: User
type: object
required:
- user_id
properties:
user_id:
type: string
example: "@foo:bar.com"
description: The user's matrix user ID.
display_name:
type: string
example: Foo
description: The display name of the user, if one exists.
avatar_url:
type: string
format: uri
example: mxc://bar.com/foo
description: The avatar url, as an [`mxc://`
URI](/client-server-api/#matrix-content-mxc-uris),
if one exists.
limited:
type: boolean
description: Indicates if the result list has been truncated by the limit.
examples:
application/json: {
response:
value: {
"results": [
{
"user_id": "@foo:bar.com",
@ -74,37 +100,26 @@ paths:
],
"limited": false
}
schema:
type: object
required: ["results", "limited"]
properties:
results:
type: array
description: Ordered by rank and then whether or not profile info is available.
items:
title: User
type: object
required: ["user_id"]
properties:
user_id:
type: string
example: "@foo:bar.com"
description: The user's matrix user ID.
display_name:
type: string
example: "Foo"
description: The display name of the user, if one exists.
avatar_url:
type: string
format: uri
example: "mxc://bar.com/foo"
description: The avatar url, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris), if one exists.
limited:
type: boolean
description: Indicates if the result list has been truncated by the limit.
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- User directory
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

52
data/api/client-server/versions.yaml
View file

@ -11,19 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Versions API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client
produces:
- application/json
title: Matrix Client-Server Versions API
version: 1.0.0
paths:
"/versions":
/versions:
get:
summary: Gets the versions of the specification supported by the server.
description: |-
@ -47,15 +40,10 @@ paths:
features in their stable releases.
operationId: getVersions
responses:
200:
"200":
description: The versions supported by the server.
examples:
application/json: {
"versions": ["r0.0.1", "v1.1"],
"unstable_features": {
"org.example.my_feature": true
}
}
content:
application/json:
schema:
type: object
properties:
@ -74,6 +62,30 @@ paths:
additionalProperties:
type: boolean
description: Whether or not the namespaced feature is supported.
required: ['versions']
required:
- versions
examples:
response:
value: {
"versions": [
"r0.0.1",
"v1.1"
],
"unstable_features": {
"org.example.my_feature": true
}
}
tags:
- Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client

79
data/api/client-server/voip.yaml
View file

@ -11,23 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Voice over IP API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Voice over IP API
version: 1.0.0
paths:
"/voip/turnServer":
/voip/turnServer:
get:
summary: Obtain TURN server credentials.
description: |-
@ -37,30 +26,19 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The TURN server credentials.
examples:
application/json: {
"username":"1443779631:@user:example.com",
"password":"JlKfBy1QwLrO20385QyAtEyIv0=",
"uris":[
"turn:turn.example.com:3478?transport=udp",
"turn:10.20.30.40:3478?transport=tcp",
"turns:10.20.30.40:443?transport=tcp"
],
"ttl":86400
}
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: |-
The username to use.
description: The username to use.
password:
type: string
description: |-
The password to use.
description: The password to use.
uris:
type: array
items:
@ -69,10 +47,43 @@ paths:
ttl:
type: integer
description: The time-to-live in seconds
required: ["username", "password", "uris", "ttl"]
429:
required:
- username
- password
- uris
- ttl
examples:
response:
value: {
"username": "1443779631:@user:example.com",
"password": "JlKfBy1QwLrO20385QyAtEyIv0=",
"uris": [
"turn:turn.example.com:3478?transport=udp",
"turn:10.20.30.40:3478?transport=tcp",
"turns:10.20.30.40:443?transport=tcp"
],
"ttl": 86400
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- VOIP
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

34
data/api/client-server/wellknown.yaml
View file

@ -11,18 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Server Discovery API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /.well-known
produces:
- application/json
title: Matrix Client-Server Server Discovery API
version: 1.0.0
paths:
"/matrix/client":
/matrix/client:
get:
summary: Gets Matrix server discovery information about the domain.
description: |-
@ -36,11 +30,25 @@ paths:
but by another webserver, to be used for discovering the homeserver URL.
operationId: getWellknown
responses:
200:
"200":
description: Server discovery information.
content:
application/json:
schema:
"$ref": "definitions/wellknown/full.yaml"
404:
$ref: definitions/wellknown/full.yaml
"404":
description: No server discovery information available.
tags:
- Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /.well-known

87
data/api/client-server/whoami.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Client-Server Account Identification API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Account Identification API
version: 1.0.0
paths:
"/account/whoami":
/account/whoami:
get:
summary: Gets information about the owner of an access token.
description: |-
@ -40,19 +31,15 @@ paths:
operationId: getTokenOwner
security:
- accessToken: []
parameters: []
responses:
200:
description:
The token belongs to a known user.
examples:
application/json: {
"user_id": "@joe:example.org",
"device_id": "ABC1234"
}
"200":
description: The token belongs to a known user.
content:
application/json:
schema:
type: object
required: ["user_id"]
required:
- user_id
properties:
user_id:
type: string
@ -72,29 +59,57 @@ paths:
When `true`, the user is a [Guest User](#guest-access). When
not present or `false`, the user is presumed to be a non-guest
user.
401:
description:
The token is not recognised
examples:
application/json: {
response:
value: {
"user_id": "@joe:example.org",
"device_id": "ABC1234"
}
"401":
description: The token is not recognised
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token."
}
"403":
description: The appservice cannot masquerade as the user or has not registered
them.
content:
application/json:
schema:
"$ref": "definitions/errors/error.yaml"
403:
description:
The appservice cannot masquerade as the user or has not registered them.
$ref: definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Application service has not registered this user."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"429":
description: This request was rate-limited.
content:
application/json:
schema:
"$ref": "definitions/errors/rate_limited.yaml"
$ref: definitions/errors/rate_limited.yaml
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

254
data/api/identity/v2_associations.yaml
View file

@ -12,51 +12,38 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Establishing Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Establishing Associations API
version: 2.0.0
paths:
"/3pid/getValidated3pid":
/3pid/getValidated3pid:
get:
summary: Check whether ownership of a 3pid was validated.
description: |-
Determines if a given 3pid has been validated by a user.
description: Determines if a given 3pid has been validated by a user.
operationId: getValidated3pidV2
security:
- accessToken: []
parameters:
- in: query
type: string
name: sid
description: The Session ID generated by the `requestToken` call.
required: true
x-example: 1234
- in: query
example: 1234
schema:
type: string
- in: query
name: client_secret
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
example: monkeys_are_GREAT
schema:
type: string
responses:
200:
"200":
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
content:
application/json:
schema:
type: object
properties:
@ -72,42 +59,61 @@ paths:
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
required:
- medium
- address
- validated_at
examples:
response:
value: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
"400":
description: |-
The session has not been validated.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The Session ID or client secret were not found.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/bind":
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
/3pid/bind:
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
@ -123,9 +129,9 @@ paths:
operationId: bindV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -143,24 +149,15 @@ paths:
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required: ["sid", "client_secret", "mxid"]
required:
- sid
- client_secret
- mxid
responses:
200:
"200":
description: The association was published.
examples:
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
content:
application/json:
schema:
type: object
properties:
@ -176,11 +173,13 @@ paths:
not_before:
type: integer
format: int64
description: A unix timestamp before which the association is not known to be valid.
description: A unix timestamp before which the association is not known to be
valid.
not_after:
type: integer
format: int64
description: A unix timestamp after which the association is not known to be valid.
description: A unix timestamp after which the association is not known to be
valid.
ts:
type: integer
format: int64
@ -192,7 +191,7 @@ paths:
association should be trusted, if you trust the verifying identity
services.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
- $ref: ../../schemas/server-signatures.yaml
required:
- address
- medium
@ -201,41 +200,65 @@ paths:
- not_after
- ts
- signatures
400:
examples:
response:
value: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
"400":
description: |-
The association was not published.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The Session ID or client secret were not found
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/unbind":
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
/3pid/unbind:
post:
summary: Remove an association between a session and a Matrix user ID.
description: |-
@ -257,9 +280,9 @@ paths:
operationId: unbindV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -296,26 +319,28 @@ paths:
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
required:
- medium
- address
required:
- threepid
- mxid
responses:
200:
"200":
description: The association was successfully removed.
examples:
application/json: {}
content:
application/json:
schema:
type: object
400:
examples:
response:
value: {}
"400":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
404:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
403:
"403":
description: |-
The credentials supplied to authenticate the request were invalid.
This may also be returned if the identity server does not support
@ -324,15 +349,38 @@ paths:
Another common error code is `M_TERMS_NOT_SIGNED` where the user
needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
501:
"404":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
"501":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

128
data/api/identity/v2_auth.yaml
View file

@ -11,22 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Authentication API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Authentication API
version: 2.0.0
paths:
"/account/register":
/account/register:
post:
summary: Exchanges an OpenID token for an access token.
description: |-
@ -34,20 +24,18 @@ paths:
access the identity server. The request body is the same as the values
returned by `/openid/request_token` in the Client-Server API.
operationId: registerAccount
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
$ref: "../client-server/definitions/openid_token.yaml"
$ref: ../client-server/definitions/openid_token.yaml
responses:
200:
"200":
description: |-
A token which can be used to authenticate future requests to the
identity server.
examples:
application/json: {
"token": "abc123_OpaqueString"
}
content:
application/json:
schema:
type: object
properties:
@ -56,42 +44,54 @@ paths:
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
required: ['token']
"/account":
required:
- token
examples:
response:
value: {
"token": "abc123_OpaqueString"
}
/account:
get:
summary: Gets account holder information for a given token.
description: |-
Gets information about what user owns the access token used in the request.
description: Gets information about what user owns the access token used in the
request.
operationId: getAccount
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The token holder's information.
examples:
application/json: {
"user_id": "@alice:example.org"
}
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
required: ['user_id']
403:
required:
- user_id
examples:
response:
value: {
"user_id": "@alice:example.org"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/account/logout":
/account/logout:
post:
summary: Logs out an access token, rendering it unusable.
description: |-
@ -100,32 +100,54 @@ paths:
operationId: logout
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The token was successfully logged out.
examples:
application/json: {}
content:
application/json:
schema:
type: object
401:
description: |-
The token is not registered or is otherwise unknown to the server.
examples:
application/json: {
response:
value: {}
"401":
description: The token is not registered or is otherwise unknown to the server.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

167
data/api/identity/v2_email_associations.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Email Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Email Associations API
version: 2.0.0
paths:
"/validate/email/requestToken":
/validate/email/requestToken:
post:
summary: Request a token for validating an email address.
description: |-
@ -51,41 +41,49 @@ paths:
operationId: emailRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
$ref: "definitions/request_email_validation.yaml"
$ref: definitions/request_email_validation.yaml
responses:
200:
"200":
description: Session created.
content:
application/json:
schema:
$ref: "definitions/sid.yaml"
400:
$ref: definitions/sid.yaml
"400":
description: |
An error occurred. Some possible errors are:
- `M_INVALID_EMAIL`: The email address provided was invalid.
- `M_EMAIL_SEND_ERROR`: The validation email could not be sent.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken":
/validate/email/submitToken:
post:
summary: Validate ownership of an email address.
description: |-
@ -110,9 +108,9 @@ paths:
operationId: emailSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -129,34 +127,44 @@ paths:
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and emailed to the user.
required: ["sid", "client_secret", "token"]
description: The token generated by the `requestToken` call and emailed to the
user.
required:
- sid
- client_secret
- token
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
"200":
description: The success of the validation.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
required:
- success
examples:
response:
value: {
"success": true
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
get:
summary: Validate ownership of an email address.
description: |-
@ -175,42 +183,63 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
example: 1234
schema:
type: string
- in: query
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
- in: query
example: monkeys_are_GREAT
schema:
type: string
- in: query
name: token
required: true
description: The token generated by the `requestToken` call and emailed to the user.
x-example: atoken
description: The token generated by the `requestToken` call and emailed to the
user.
example: atoken
schema:
type: string
responses:
200:
"200":
description: Email address is validated.
"3xx":
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"3XX":
description: |-
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"4XX":
description: Validation failed.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

92
data/api/identity/v2_invitation_signing.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Ephemeral Invitation Signing API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Ephemeral Invitation Signing API
version: 2.0.0
paths:
"/sign-ed25519":
/sign-ed25519:
post:
summary: Sign invitation details
description: |-
@ -38,9 +28,9 @@ paths:
operationId: blindlySignStuffV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -57,11 +47,17 @@ paths:
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
required: ["mxid", "token", "private_key"]
description: The private key, encoded as [Unpadded
base64](/appendices/#unpadded-base64).
required:
- mxid
- token
- private_key
responses:
200:
"200":
description: The signed JSON of the mxid, sender, and token.
content:
application/json:
schema:
type: object
properties:
@ -75,13 +71,18 @@ paths:
type: object
description: The signature of the mxid, sender, and token.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
- $ref: ../../schemas/server-signatures.yaml
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
required:
- mxid
- sender
- signatures
- token
examples:
application/json: {
response:
value: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
@ -91,23 +92,44 @@ paths:
},
"token": "abc123"
}
404:
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The token was not found.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

129
data/api/identity/v2_lookup.yaml
View file

@ -15,22 +15,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Lookup API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Lookup API
version: 2.0.0
paths:
"/hash_details":
/hash_details:
get:
summary: Gets hash function information from the server.
description: |-
@ -39,15 +29,11 @@ paths:
operationId: getHashDetails
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The hash function information.
examples:
application/json: {
"lookup_pepper": "matrixrocks",
"algorithms": ["none", "sha256"]
}
content:
application/json:
schema:
type: object
properties:
@ -62,10 +48,20 @@ paths:
type: array
items:
type: string
description: |-
The algorithms the server supports. Must contain at least `sha256`.
required: ['lookup_pepper', 'algorithms']
"/lookup":
description: The algorithms the server supports. Must contain at least `sha256`.
required:
- lookup_pepper
- algorithms
examples:
response:
value: {
"lookup_pepper": "matrixrocks",
"algorithms": [
"none",
"sha256"
]
}
/lookup:
post:
summary: Look up Matrix User IDs for a set of 3PIDs.
description: |-
@ -75,9 +71,9 @@ paths:
operationId: lookupUsersV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -86,13 +82,13 @@ paths:
description: |-
The algorithm the client is using to encode the `addresses`. This
should be one of the available options from `/hash_details`.
example: "sha256"
example: sha256
pepper:
type: string
description: |-
The pepper from `/hash_details`. This is required even when the
`algorithm` does not make use of it.
example: "matrixrocks"
example: matrixrocks
addresses:
type: array
items:
@ -105,21 +101,18 @@ paths:
Note that addresses are case sensitive: review the
[3PID Types](/appendices#3pid-types) to verify the intended case an
identifier should be prior to submission/hashing.
example: [
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
"nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
]
required: ['algorithm', 'pepper', 'addresses']
example:
- 4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc
- nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I
required:
- algorithm
- pepper
- addresses
responses:
200:
description:
The associations for any matched `addresses`.
examples:
application/json: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
"200":
description: The associations for any matched `addresses`.
content:
application/json:
schema:
type: object
properties:
@ -132,21 +125,41 @@ paths:
title: AssociatedMappings
additionalProperties:
type: string
required: ['mappings']
400:
description:
The client's request was invalid in some way. One possible problem could
be the `pepper` being invalid after the server has rotated it - this is
presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make
a call to `/hash_details` to get a new pepper in this scenario, being
careful to avoid retry loops.
`M_INVALID_PARAM` can also be returned to indicate the client supplied
an `algorithm` that is unknown to the server.
required:
- mappings
examples:
application/json: {
response:
value: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
"400":
description: |-
The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops.
`M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PEPPER",
"error": "Unknown or invalid pepper - has it been rotated?"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

164
data/api/identity/v2_phone_associations.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Phone Number Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Phone Number Associations API
version: 2.0.0
paths:
"/validate/msisdn/requestToken":
/validate/msisdn/requestToken:
post:
summary: Request a token for validating a phone number.
description: |-
@ -51,17 +41,19 @@ paths:
operationId: msisdnRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
$ref: "definitions/request_msisdn_validation.yaml"
$ref: definitions/request_msisdn_validation.yaml
responses:
200:
"200":
description: Session created.
content:
application/json:
schema:
$ref: "definitions/sid.yaml"
400:
$ref: definitions/sid.yaml
"400":
description: |
An error occurred. Some possible errors are:
@ -69,25 +61,31 @@ paths:
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken":
/validate/msisdn/submitToken:
post:
summary: Validate ownership of a phone number.
description: |-
@ -112,9 +110,9 @@ paths:
operationId: msisdnSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -131,34 +129,44 @@ paths:
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and sent to the user.
required: ["sid", "client_secret", "token"]
description: The token generated by the `requestToken` call and sent to the
user.
required:
- sid
- client_secret
- token
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
"200":
description: The success of the validation.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
required:
- success
examples:
response:
value: {
"success": true
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
get:
summary: Validate ownership of a phone number.
description: |-
@ -177,42 +185,62 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
example: 1234
schema:
type: string
- in: query
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
- in: query
example: monkeys_are_GREAT
schema:
type: string
- in: query
name: token
required: true
description: The token generated by the `requestToken` call and sent to the user.
x-example: atoken
example: atoken
schema:
type: string
responses:
200:
"200":
description: Phone number is validated.
"3xx":
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"3XX":
description: |-
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"4XX":
description: Validation failed.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

36
data/api/identity/v2_ping.yaml
View file

@ -13,19 +13,12 @@
# 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"
openapi: 3.1.0
info:
title: "Matrix Identity Service Ping API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
title: Matrix Identity Service Ping API
version: 2.0.0
paths:
"/v2":
/v2:
get:
summary: Checks that an identity server is available at this API endpoint.
description: |-
@ -38,9 +31,24 @@ paths:
by entities acting as a client for the identity server.
operationId: pingV2
responses:
200:
"200":
description: An identity server is ready to serve requests.
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

128
data/api/identity/v2_pubkey.yaml
View file

@ -12,61 +12,58 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Public Key API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
title: Matrix Identity Service Public Key API
version: 2.0.0
paths:
"/pubkey/{keyId}":
get:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
description: Get the public key for the passed key ID.
operationId: getPubKeyV2
parameters:
- in: path
type: string
name: keyId
required: true
description: |-
The ID of the key. This should take the form algorithm:identifier
where algorithm identifies the signing algorithm, and the identifier
is an opaque string.
x-example: "ed25519:0"
example: ed25519:0
schema:
type: string
responses:
200:
description:
The public key exists.
examples:
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
"200":
description: The public key exists.
content:
application/json:
schema:
type: object
properties:
public_key:
type: string
description: Unpadded Base64 encoded public key.
required: ['public_key']
404:
description:
The public key was not found.
required:
- public_key
examples:
application/json: {
response:
value: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
"404":
description: The public key was not found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid":
/pubkey/isvalid:
get:
summary: Check whether a long-term public key is valid.
description: |-
@ -75,53 +72,70 @@ paths:
operationId: isPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: string
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
"200":
description: The validity of the public key.
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
required:
- valid
examples:
response:
value: {
"valid": true
}
/pubkey/ephemeral/isvalid:
get:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
description: Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: string
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
"200":
description: The validity of the public key.
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
required:
- valid
examples:
response:
value: {
"valid": true
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2

102
data/api/identity/v2_store_invite.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Store Invitations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Store Invitations API
version: 2.0.0
paths:
"/store-invite":
/store-invite:
post:
summary: Store pending invitations to a user's 3pid.
description: |-
@ -62,20 +52,20 @@ paths:
operationId: storeInviteV2
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: "email"
example: email
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
example: foo@example.com
room_id:
type: string
description: The Matrix room ID to which the user is invited
@ -96,37 +86,44 @@ paths:
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the `m.room.avatar` state event.
example: "mxc://example.org/s0meM3dia"
example: mxc://example.org/s0meM3dia
room_join_rules:
type: string
description: |-
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: "public"
example: public
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
example: Bob's Emporium of Messages
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
example: Bob Smith
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
description: The Content URI for the avatar of the user ID initiating the
invite.
example: mxc://example.org/an0th3rM3dia
room_type:
type: string
description: |-
The `type` from the `m.room.create` event's `content`. If the create event doesn't
have a specified `type`, this field is not included.
example: "m.space"
required: ["medium", "address", "room_id", "sender"]
example: m.space
required:
- medium
- address
- room_id
- sender
responses:
200:
"200":
description: The invitation was stored.
content:
application/json:
schema:
type: object
properties:
@ -155,13 +152,19 @@ paths:
The URI of an endpoint where the validity of this key can be checked
by passing it as a `public_key` query parameter. See
[key management](/identity-service-api/#key-management).
required: ['public_key', 'key_validity_url']
required:
- public_key
- key_validity_url
display_name:
type: string
description: The generated (redacted) display name.
required: ['token', 'public_keys', 'display_name']
required:
- token
- public_keys
- display_name
examples:
application/json: {
response:
value: {
"token": "sometoken",
"public_keys": [
{
@ -175,29 +178,50 @@ paths:
],
"display_name": "f...@b..."
}
400:
"400":
description: |
An error has occurred.
If the 3pid is already bound to a Matrix user ID, the error code
will be `M_THREEPID_IN_USE`. If the medium is unsupported, the
error code will be `M_UNRECOGNIZED`.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

155
data/api/identity/v2_terms.yaml
View file

@ -11,22 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Terms of Service API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Identity Service Terms of Service API
version: 2.0.0
paths:
"/terms":
/terms:
get:
summary: Gets the terms of service offered by the server.
description: |-
@ -34,13 +24,60 @@ paths:
to filter through the terms to determine which terms need acceptance from the
user. Note that this endpoint does not require authentication.
operationId: getTerms
parameters: []
responses:
200:
"200":
description: The terms of service offered by the server.
content:
application/json:
schema:
type: object
properties:
policies:
type: object
title: Policy Map
description: |-
The terms of service offered by the server.
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required:
- version
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy
description: The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the `m.accepted_terms` collection.
required:
- name
- url
required:
- policies
examples:
application/json: {
response:
value: {
"policies": {
"terms_of_service": {
"version": "2.0",
@ -66,49 +103,6 @@ paths:
}
}
}
schema:
type: object
properties:
policies:
type: object
title: Policy Map
description: |-
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required: ['version']
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy
description: |-
The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the `m.accepted_terms` collection.
required: ['name', 'url']
required: ['policies']
post:
summary: Indicates acceptance of terms to the server.
description: |-
@ -126,9 +120,9 @@ paths:
operationId: agreeToTerms
security:
- accessToken: []
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -137,13 +131,32 @@ paths:
items:
type: string
description: The URLs the user is accepting in this request.
example: "https://example.org/somewhere/terms-2.0-en.html"
required: ['user_accepts']
example: https://example.org/somewhere/terms-2.0-en.html
required:
- user_accepts
responses:
200:
description: |-
The server has considered the user as having accepted the provided URLs.
examples:
application/json: {}
"200":
description: The server has considered the user as having accepted the provided
URLs.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

46
data/api/identity/versions.yaml
View file

@ -11,18 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Versions API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
title: Matrix Identity Service Versions API
version: 1.0.0
paths:
"/versions":
/versions:
get:
x-addedInMatrixVersion: "1.1"
summary: Gets the versions of the specification supported by the server.
@ -36,12 +30,10 @@ paths:
All supported versions, including patch versions, are reported by the server.
operationId: getVersions
responses:
200:
"200":
description: The versions supported by the server.
examples:
application/json: {
"versions": ["r0.2.0", "r0.2.1", "v1.1"]
}
content:
application/json:
schema:
type: object
properties:
@ -51,4 +43,26 @@ paths:
items:
type: string
description: The supported versions.
required: ['versions']
required:
- versions
examples:
response:
value: {
"versions": [
"r0.2.0",
"r0.2.1",
"v1.1"
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

88
data/api/push-gateway/push_notifier.yaml
View file

@ -12,21 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Push Notification API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/push/v1
consumes:
- application/json
produces:
- application/json
title: Matrix Push Notification API
version: 1.0.0
paths:
"/notify":
/notify:
post:
summary: Notify a push gateway about an event.
description: |-
@ -48,11 +39,9 @@ paths:
This means that the HTTP path may be different depending on the push
gateway.
operationId: notify
parameters:
- in: body
name: notification
description: Information about the push notification.
required: true
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -70,7 +59,7 @@ paths:
"body": "I'm floating in a most peculiar way."
},
"counts": {
"unread" : 2,
"unread": 2,
"missed_calls": 1
},
"devices": [
@ -78,7 +67,7 @@ paths:
"app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678,
"data" : {},
"data": {},
"tweaks": {
"sound": "bing"
}
@ -86,13 +75,15 @@ paths:
]
}
}
required: ["notification"]
required:
- notification
properties:
notification:
type: object
title: Notification
description: Information about the push notification
required: ["devices"]
required:
- devices
properties:
event_id:
type: string
@ -110,12 +101,10 @@ paths:
Matrix event.
type:
type: string
description: |-
The type of the event as in the event's `type` field.
description: The type of the event as in the event's `type` field.
sender:
type: string
description: |-
The sender of the event as in the corresponding event field.
description: The sender of the event as in the corresponding event field.
sender_display_name:
type: string
description: |-
@ -135,7 +124,9 @@ paths:
member event is equal to the user's Matrix ID).
prio:
type: string
enum: ["high", "low"]
enum:
- high
- low
description: |-
The priority of the notification. If omitted, `high` is
assumed. This may be used by push gateways to deliver less
@ -169,16 +160,15 @@ paths:
devices:
type: array
title: Devices
description: |-
This is an array of devices that the notification should be sent to.
description: This is an array of devices that the notification should be sent
to.
items:
type: object
title: Device
properties:
app_id:
type: string
description: |-
The `app_id` given when the pusher was created.
description: The `app_id` given when the pusher was created.
pushkey:
type: string
description: The `pushkey` given when the pusher was created.
@ -201,14 +191,16 @@ paths:
description: |-
A dictionary of customisations made to the way this
notification is to be presented. These are added by push rules.
required: ['app_id', 'pushkey']
required:
- app_id
- pushkey
description: Information about the push notification.
required: true
responses:
200:
"200":
description: A list of rejected push keys.
examples:
application/json: {
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
content:
application/json:
schema:
type: object # empty json object
properties:
@ -226,4 +218,24 @@ paths:
items:
type: string
description: A pushkey that has been rejected.
required: ['rejected']
required:
- rejected
examples:
response:
value: {
"rejected": [
"V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/push/v1

90
data/api/server-server/backfill.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Events API
version: 1.0.0
paths:
"/backfill/{roomId}":
get:
@ -40,26 +29,30 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID to backfill.
required: true
x-example: "!SomeRoom:matrix.org"
example: "!SomeRoom:matrix.org"
schema:
type: string
- in: query
name: v
description: The event IDs to backfill from.
required: true
example:
- $abc123:matrix.org
schema:
type: array
items:
type: string
description: The event IDs to backfill from.
required: true
x-example: ["$abc123:matrix.org"]
- in: query
name: limit
type: integer
description: The maximum number of PDUs to retrieve, including the given events.
required: true
x-example: 2
example: 2
schema:
type: integer
responses:
200:
"200":
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
@ -71,8 +64,10 @@ paths:
Due to historical reasons, it is possible that events which were previously accepted
would now be rejected by these limitations. The events should be rejected per usual by
the `/send`, `/get_missing_events`, and remaining endpoints.
content:
application/json:
schema:
$ref: "definitions/unlimited_pdu_transaction.yaml"
$ref: definitions/unlimited_pdu_transaction.yaml
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
@ -86,12 +81,14 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID to search in.
required: true
x-example: "!SomeRoom:matrix.org"
- in: body
name: body
example: "!SomeRoom:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -110,19 +107,25 @@ paths:
the previous events of `latest_events`.
items:
type: string
example: ["$missing_event:example.org"]
example:
- $missing_event:example.org
latest_events:
type: array
description: The event IDs to retrieve the previous events for.
items:
type: string
example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"]
required: ['earliest_events', 'latest_events']
example:
- $event_that_has_the_missing_event_as_a_previous_event:example.org
required:
- earliest_events
- latest_events
responses:
200:
"200":
description: |-
The previous events for `latest_events`, excluding any `earliest_events`, up to the
provided `limit`.
content:
application/json:
schema:
type: object
properties:
@ -134,10 +137,29 @@ paths:
items:
type: object
title: PDU
required: ['events']
required:
- events
examples:
application/json: {
response:
value: {
"events": [
{"$ref": "examples/minimal_pdu.json"}
{
"$ref": "examples/minimal_pdu.json"
}
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

2
data/api/server-server/definitions/unsigned_pdu_base.yaml
View file

@ -56,6 +56,7 @@ properties:
maxItems: 2
minItems: 2
items:
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
@ -91,6 +92,7 @@ properties:
maxItems: 2
minItems: 2
items:
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"

54
data/api/server-server/event_auth.yaml
View file

@ -11,46 +11,38 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Event Authorization API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Event Authorization API
version: 1.0.0
paths:
"/event_auth/{roomId}/{eventId}":
get:
summary: Get the auth chain for a given event
description: |-
Retrieves the complete auth chain for a given event.
description: Retrieves the complete auth chain for a given event.
operationId: getEventAuth
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to get the auth chain for.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID to get the auth chain of.
required: true
x-example: "$helloworld:example.org"
example: $helloworld:example.org
schema:
type: string
responses:
200:
"200":
description: The auth chain for the event.
content:
application/json:
schema:
type: object
properties:
@ -66,5 +58,21 @@ paths:
title: PDU
properties: {}
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain']
$ref: examples/minimal_pdu.json
required:
- auth_chain
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

168
data/api/server-server/events.yaml
View file

@ -11,47 +11,41 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Events API
version: 1.0.0
paths:
"/state/{roomId}":
get:
summary: Get all the state of a given room
description: |-
Retrieves a snapshot of a room's state at a given event.
description: Retrieves a snapshot of a room's state at a given event.
operationId: getRoomState
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
example: $helloworld:matrix.org
schema:
type: string
responses:
200:
"200":
description: |-
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
content:
application/json:
schema:
type: object
properties:
@ -71,7 +65,7 @@ paths:
for precise event formats.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
$ref: examples/minimal_pdu.json
pdus:
type: array
description: |-
@ -87,8 +81,10 @@ paths:
for precise event formats.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain', 'pdus']
$ref: examples/minimal_pdu.json
required:
- auth_chain
- pdus
"/state_ids/{roomId}":
get:
summary: Get all the state event IDs of a given room
@ -102,22 +98,26 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
example: $helloworld:matrix.org
schema:
type: string
responses:
200:
"200":
description: |-
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
content:
application/json:
schema:
type: object
properties:
@ -128,46 +128,54 @@ paths:
of the room, and their authorization events, recursively.
items:
type: string
example: ["$an_event:example.org"]
example:
- $an_event:example.org
pdu_ids:
type: array
description: |-
The fully resolved state of the room at the given event.
description: The fully resolved state of the room at the given event.
items:
type: string
example: ["$an_event:example.org"]
required: ['auth_chain_ids', 'pdu_ids']
404:
example:
- $an_event:example.org
required:
- auth_chain_ids
- pdu_ids
"404":
description: |-
The given `event_id` was not found or the server doesn't know about the state at
that event to return anything useful.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
}
schema:
"$ref": "../client-server/definitions/errors/error.yaml"
"/event/{eventId}":
get:
summary: Get a single event
description: |-
Retrieves a single event.
description: Retrieves a single event.
operationId: getEvent
security:
- signedRequest: []
parameters:
- in: path
name: eventId
type: string
description: The event ID to get.
required: true
x-example: "$abc123:matrix.org"
responses:
200:
description: A transaction containing a single PDU which is the event requested.
example: $abc123:matrix.org
schema:
$ref: "definitions/single_pdu_transaction.yaml"
type: string
responses:
"200":
description: A transaction containing a single PDU which is the event requested.
content:
application/json:
schema:
$ref: definitions/single_pdu_transaction.yaml
"/timestamp_to_event/{roomId}":
get:
summary: Get the closest event ID to the given timestamp
@ -202,55 +210,79 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room to search
required: true
x-example: "!636q39766251:matrix.org"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: query
type: integer
name: ts
description: |-
The timestamp to search from, as given in milliseconds
since the Unix epoch.
required: true
x-example: 1432684800000
example: 1432684800000
schema:
type: integer
- in: query
type: string
enum: [f, b]
name: dir
description: |-
The direction in which to search. `f` for forwards, `b` for backwards.
description: The direction in which to search. `f` for forwards, `b` for
backwards.
required: true
x-example: f
example: f
schema:
type: string
enum:
- f
- b
responses:
200:
description: |-
An event was found matching the search parameters.
"200":
description: An event was found matching the search parameters.
content:
application/json:
schema:
type: object
properties:
event_id:
type: string
description: |-
The ID of the event found
description: The ID of the event found
origin_server_ts:
type: integer
description: |-
The event's timestamp, in milliseconds since the Unix epoch.
required: ['event_id', 'origin_server_ts']
description: The event's timestamp, in milliseconds since the Unix epoch.
required:
- event_id
- origin_server_ts
examples:
application/json: {
response:
value: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
404:
description: |-
No event was found.
"404":
description: No event was found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
schema:
"$ref": "../client-server/definitions/errors/error.yaml"
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

79
data/api/server-server/invites-v1.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Invite User To Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Invite User To Room API
version: 1.0.0
paths:
"/invite/{roomId}/{eventId}":
put:
@ -49,23 +38,24 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that the user is being invited to.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the invite event, generated by the inviting server.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
allOf:
- $ref: "definitions/invite_event.yaml"
- $ref: definitions/invite_event.yaml
- type: object
properties:
unsigned:
@ -81,9 +71,10 @@ paths:
An optional list of [stripped state events](/client-server-api/#stripped-state)
to help the receiver of the invite identify the room.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
$ref: ../../event-schemas/examples/invite_room_state.json
type: object
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
@ -100,17 +91,21 @@ paths:
},
}
}
required: true
responses:
200:
"200":
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched. Note that events have a different format depending on the
room version - check the [room version specification](/rooms) for precise event formats.
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
@ -119,10 +114,12 @@ paths:
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
$ref: definitions/invite_event.yaml
required:
- event
examples:
application/json: [
response:
value: [
200,
{
"event": {
@ -166,17 +163,35 @@ paths:
}
}
]
403:
"403":
description: |-
The invite is not allowed. This could be for a number of reasons, including:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

112
data/api/server-server/invites-v2.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Invite User To Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Invite User To Room API
version: 1.0.0
paths:
"/invite/{roomId}/{eventId}":
put:
@ -53,20 +42,21 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that the user is being invited to.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the invite event, generated by the inviting server.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -75,17 +65,19 @@ paths:
description: The version of the room where the user is being invited to.
example: "2"
event:
$ref: "definitions/invite_event.yaml"
$ref: definitions/invite_event.yaml
invite_room_state:
type: array
description: |-
An optional list of [stripped state events](/client-server-api/#stripped-state)
to help the receiver of the invite identify the room.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
required: ['room_version', 'event']
$ref: ../../event-schemas/examples/invite_room_state.json
required:
- room_version
- event
example: {
"room_version": "2",
"event": {
@ -105,22 +97,27 @@ paths:
}
}
}
required: true
responses:
200:
"200":
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched. Note that events have a different format depending on the
room version - check the [room version specification](/rooms) for precise event formats.
content:
application/json:
schema:
type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
$ref: definitions/invite_event.yaml
required:
- event
examples:
application/json: {
response:
value: {
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
@ -161,21 +158,7 @@ paths:
}
}
}
403:
description: |-
The invite is not allowed. This could be for a number of reasons, including:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
400:
"400":
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the `ver`
@ -183,9 +166,11 @@ paths:
The error should be passed through to clients so that they
may give better feedback to users.
content:
application/json:
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
@ -194,8 +179,41 @@ paths:
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
response:
value: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
"403":
description: |-
The invite is not allowed. This could be for a number of reasons, including:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v2
components:
securitySchemes:
$ref: definitions/security.yaml

192
data/api/server-server/joins-v1.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Join Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Join Room API
version: 1.0.0
paths:
"/make_join/{roomId}/{userId}":
get:
@ -40,33 +29,40 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: userId
type: string
description: The user ID the join event will be for.
required: true
x-example: "@someone:example.org"
- in: query
type: array
items:
example: "@someone:example.org"
schema:
type: string
- in: query
name: ver
description: |-
The room versions the sending server has support for. Defaults
to `[1]`.
x-example: ["1", "2"]
example:
- "1"
- "2"
schema:
type: array
items:
type: string
responses:
200:
"200":
description: |-
A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that
events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
content:
application/json:
schema:
type: object
properties:
@ -91,7 +87,7 @@ paths:
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -100,7 +96,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
@ -109,12 +105,13 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: "join"
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
@ -127,7 +124,8 @@ paths:
the room being joined that is able to issue invites to other
users. This is used in later validation of the auth rules for
the `m.room.member` event.
required: ['membership']
required:
- membership
required:
- state_key
- origin
@ -136,7 +134,8 @@ paths:
- content
- sender
examples:
application/json: {
response:
value: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
@ -151,7 +150,7 @@ paths:
}
}
}
400:
"400":
description: |-
The request is invalid, the room the server is attempting
to join has a version that is not listed in the `ver`
@ -177,9 +176,11 @@ paths:
resident server would be unable to meet the auth rules governing
`join_authorised_via_users_server` on the resulting `m.room.member`
event.
content:
application/json:
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
@ -188,34 +189,40 @@ paths:
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
response:
value: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
403:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"403":
description: |-
The room that the joining server is attempting to join does not permit the user
to join.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room",
}
404:
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room"
}
"404":
description: |-
The room that the joining server is attempting to join is unknown
to the receiving server.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
"error": "Unknown room"
}
"/send_join/{roomId}/{eventId}":
put:
deprecated: true
@ -237,20 +244,21 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the join event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -261,7 +269,7 @@ paths:
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -270,7 +278,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
@ -279,12 +287,13 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: "join"
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
@ -302,7 +311,8 @@ paths:
valid signature on the event. If the resident server is receiving
the `/send_join` request, the signature must be added before sending
or persisting the event to other servers.
required: ['membership']
required:
- membership
required:
- state_key
- sender
@ -310,27 +320,18 @@ paths:
- origin_server_ts
- type
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
required: true
responses:
200:
description: |-
The join event has been accepted into the room.
"200":
description: The join event has been accepted into the room.
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
@ -354,9 +355,6 @@ paths:
description: |-
The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
state:
type: array
description: |-
@ -370,17 +368,43 @@ paths:
description: |-
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
required: ["auth_chain", "state", "origin"]
required:
- auth_chain
- state
- origin
examples:
application/json: [
response:
value: [
200,
{
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}],
"event": {"$ref": "examples/pdu_v4_join_membership.json"}
"auth_chain": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"state": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"event": {
"$ref": "examples/pdu_v4_join_membership.json"
}
}
]
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

200
data/api/server-server/joins-v2.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Join Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Join Room API
version: 1.0.0
paths:
# Note: there is no v2 of make_join (yet)
"/send_join/{roomId}/{eventId}":
@ -55,19 +44,20 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the join event.
required: true
x-example: "$abc123:example.org"
example: $abc123:example.org
schema:
type: string
- in: query
name: omit_members
type: boolean
description: |-
If `true`, indicates that that calling server can accept a reduced
response, in which membership events are omitted from `state` and
@ -83,10 +73,11 @@ paths:
response `state` field, and include the auth chains for these
membership events in the response `auth_chain` field.
x-addedInMatrixVersion: "1.6"
- in: body
name: body
type: object
required: true
schema:
type: boolean
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -97,7 +88,7 @@ paths:
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -106,7 +97,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
@ -115,12 +106,13 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: "join"
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
@ -138,7 +130,8 @@ paths:
valid signature on the event. If the resident server is receiving
the `/send_join` request, the signature must be added before sending
or persisting the event to other servers.
required: ['membership']
required:
- membership
required:
- state_key
- sender
@ -158,51 +151,12 @@ paths:
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
required: true
responses:
400:
description: |-
The request is invalid in some way.
The error should be passed through to clients so that they
may give better feedback to users.
New in `v1.2`, the following error conditions might happen:
If the room is [restricted](/client-server-api/#restricted-rooms)
and none of the conditions can be validated by the server then
the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can
happen if the server does not know about any of the rooms listed
as conditions, for example.
`M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different
server should be attempted for the join. This is typically because
the resident server can see that the joining user satisfies one or
more conditions, such as in the case of
[restricted rooms](/client-server-api/#restricted-rooms), but the
resident server would be unable to meet the auth rules governing
`join_authorised_via_users_server` on the resulting `m.room.member`
event.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_UNABLE_TO_GRANT_JOIN",
"error": "This server cannot send invites to you."
}
403:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
description: |-
The room that the joining server is attempting to join does not permit the user
to join.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room",
}
200:
description: |-
The join event has been accepted into the room.
"200":
description: The join event has been accepted into the room.
content:
application/json:
schema:
type: object
properties:
@ -230,9 +184,6 @@ paths:
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
@ -249,12 +200,8 @@ paths:
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
permit omission of membership events.
"1.6": permit omission of membership events.
event:
type: object
title: SignedMembershipEvent
@ -272,13 +219,92 @@ paths:
A list of the servers active in the room (ie, those with joined members) before the join.
items:
type: string
required: ["auth_chain", "state", "origin"]
required:
- auth_chain
- state
- origin
examples:
application/json: {
response:
value: {
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}],
"event": {"$ref": "examples/pdu_v4_join_membership.json"},
"members_omitted": true,
"servers_in_room": ["matrix.org", "example.com"]
"auth_chain": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"state": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"event": {
"$ref": "examples/pdu_v4_join_membership.json"
},
"members_omitted": true,
"servers_in_room": [
"matrix.org",
"example.com"
]
}
"400":
description: |-
The request is invalid in some way.
The error should be passed through to clients so that they
may give better feedback to users.
New in `v1.2`, the following error conditions might happen:
If the room is [restricted](/client-server-api/#restricted-rooms)
and none of the conditions can be validated by the server then
the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can
happen if the server does not know about any of the rooms listed
as conditions, for example.
`M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different
server should be attempted for the join. This is typically because
the resident server can see that the joining user satisfies one or
more conditions, such as in the case of
[restricted rooms](/client-server-api/#restricted-rooms), but the
resident server would be unable to meet the auth rules governing
`join_authorised_via_users_server` on the resulting `m.room.member`
event.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNABLE_TO_GRANT_JOIN",
"error": "This server cannot send invites to you."
}
"403":
description: |-
The room that the joining server is attempting to join does not permit the user
to join.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v2
components:
securitySchemes:
$ref: definitions/security.yaml

63
data/api/server-server/keys_query.yaml
View file

@ -11,19 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Key Exchange API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
consumes:
- application/json
produces:
- application/json
title: Matrix Federation Key Exchange API
version: 1.0.0
paths:
"/query/{serverName}":
get:
@ -35,38 +26,42 @@ paths:
parameters:
- in: path
name: serverName
type: string
description: The server's DNS name to query
required: true
x-example: matrix.org
example: matrix.org
schema:
type: string
- in: query
name: minimum_valid_until_ts
type: integer
format: int64
description: |-
A millisecond POSIX timestamp in milliseconds indicating when the returned
certificates will need to be valid until to be useful to the requesting server.
If not supplied, the current time as determined by the notary server is used.
required: false
x-example: 1234567890
example: 1234567890
schema:
type: integer
format: int64
responses:
200:
"200":
description: |-
The keys for the server, or an empty array if the server could not be reached
and no cached keys were available.
content:
application/json:
schema:
$ref: "definitions/keys_query_response.yaml"
"/query":
$ref: definitions/keys_query_response.yaml
/query:
post:
summary: Query for several server's keys
description: |-
Query for keys from multiple servers in a batch format. The receiving (notary)
server must sign the keys returned by the queried servers.
operationId: bulkPerspectivesKeyQuery
parameters:
- in: body
name: body
requestBody:
content:
application/json:
schema:
type: object
example: {
@ -93,7 +88,6 @@ paths:
given.
additionalProperties:
type: object
name: ServerName
description: The server names to query.
additionalProperties:
type: object
@ -111,12 +105,27 @@ paths:
If not supplied, the current time as determined by the notary
server is used.
example: 1234567890
required: ['server_keys']
required:
- server_keys
responses:
200:
"200":
description: |-
The keys for the queried servers, signed by the notary server. Servers which
are offline and have no cached keys will not be included in the result. This
may result in an empty array.
content:
application/json:
schema:
$ref: "definitions/keys_query_response.yaml"
$ref: definitions/keys_query_response.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/key/v2

33
data/api/server-server/keys_server.yaml
View file

@ -11,19 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Key Exchange API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
produces:
- application/json
title: Matrix Federation Key Exchange API
version: 1.0.0
paths:
"/server":
/server:
get:
summary: Get the homeserver's public key(s)
description: |-
@ -44,7 +37,21 @@ paths:
checked.
operationId: getServerKey
responses:
200:
"200":
description: The homeserver's keys
content:
application/json:
schema:
$ref: "definitions/keys.yaml"
$ref: definitions/keys.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/key/v2

209
data/api/server-server/knocks.yaml
View file

@ -11,21 +11,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Knock Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Knock Room API
version: 1.0.0
paths:
"/make_knock/{roomId}/{userId}":
get:
@ -40,40 +29,45 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be knocked.
required: true
x-example: "!abc123:example.org"
example: "!abc123:example.org"
schema:
type: string
- in: path
name: userId
type: string
description: The user ID the knock event will be for.
required: true
x-example: "@someone:example.org"
example: "@someone:example.org"
schema:
type: string
- in: query
name: ver
description: The room versions the sending server has support for.
required: true # knocking was supported in v7
example:
- "1"
- "7"
schema:
type: array
items:
type: string
name: ver
description: |-
The room versions the sending server has support for.
required: true # knocking was supported in v7
x-example: ["1", "7"]
responses:
200:
"200":
description: |-
A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms)
handshake. Note that events have a different format depending on room version - check the
[room version specification](/rooms) for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
content:
application/json:
schema:
type: object
properties:
room_version:
type: string
description: |-
The version of the room where the server is trying to knock.
description: The version of the room where the server is trying to knock.
example: "7"
event:
description: |-
@ -90,7 +84,7 @@ paths:
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -99,7 +93,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the knocking member.
@ -108,13 +102,15 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "knock"}
example:
membership: knock
properties:
membership:
type: string
description: The value `knock`.
example: "knock"
required: ['membership']
example: knock
required:
- membership
required:
- state_key
- origin
@ -126,7 +122,8 @@ paths:
- room_version # knocking was added in v7
- event
examples:
application/json: {
response:
value: {
"room_version": "7",
"event": {
"room_id": "!somewhere:example.org",
@ -140,7 +137,7 @@ paths:
}
}
}
400:
"400":
description: |-
The request is invalid or the room the server is attempting
to knock upon has a version that is not listed in the `ver`
@ -148,9 +145,11 @@ paths:
The error should be passed through to clients so that they
may give better feedback to users.
content:
application/json:
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
@ -159,36 +158,42 @@ paths:
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
response:
value: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to knock on this room",
"room_version": "7"
}
404:
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
}
403:
"403":
description: |-
The knocking server or user is not permitted to knock on the room, such as when the
server/user is banned or the room is not set up for receiving knocks.
content:
application/json:
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- $ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room",
"error": "You are not permitted to knock on this room"
}
"404":
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
"/send_knock/{roomId}/{eventId}":
put:
x-addedInMatrixVersion: "1.1"
@ -207,20 +212,21 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be knocked upon.
required: true
x-example: "!abc123:example.org"
example: "!abc123:example.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the knock event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -231,7 +237,7 @@ paths:
origin:
type: string
description: The name of the knocking homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -240,7 +246,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the knocking member.
@ -249,13 +255,15 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "knock"}
example:
membership: knock
properties:
membership:
type: string
description: The value `knock`.
example: "knock"
required: ['membership']
example: knock
required:
- membership
required:
- state_key
- sender
@ -274,50 +282,77 @@ paths:
"membership": "knock"
}
}
required: true
responses:
200:
"200":
description: |-
Information about the room to pass along to clients regarding the
knock.
content:
application/json:
schema:
type: object
properties:
knock_room_state:
type: array
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
description: |-
A list of [stripped state events](/client-server-api/#stripped-state)
to help the initiator of the knock identify the room.
example:
$ref: "../../event-schemas/examples/knock_room_state.json"
required: ['knock_room_state']
$ref: ../../event-schemas/examples/knock_room_state.json
required:
- knock_room_state
examples:
application/json: {
"knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"}
response:
value: {
"knock_room_state": {
"$ref": "../../event-schemas/examples/knock_room_state.json"
}
404:
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
}
403:
"403":
description: |-
The knocking server or user is not permitted to knock on the room, such as when the
server/user is banned or the room is not set up for receiving knocks.
content:
application/json:
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- $ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room",
"error": "You are not permitted to knock on this room"
}
"404":
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

126
data/api/server-server/leaving-v1.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Leave Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Leave Room API
version: 1.0.0
paths:
"/make_leave/{roomId}/{userId}":
get:
@ -40,24 +29,28 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: userId
type: string
description: The user ID the leave event will be for.
required: true
x-example: "@someone:example.org"
example: "@someone:example.org"
schema:
type: string
responses:
200:
"200":
description: |-
A template to be used to call `/send_leave`. Note that
events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
content:
application/json:
schema:
type: object
properties:
@ -82,7 +75,7 @@ paths:
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -91,7 +84,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
@ -100,13 +93,15 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
example: leave
required:
- membership
required:
- state_key
- sender
@ -115,7 +110,8 @@ paths:
- type
- content
examples:
application/json: {
response:
value: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
@ -129,13 +125,16 @@ paths:
}
}
}
403:
description: |-
The request is not authorized. This could mean that the user is not in the room.
"403":
description: The request is not authorized. This could mean that the user is not
in the room.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User is not in the room."
}
@ -160,20 +159,21 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the leave event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -184,7 +184,7 @@ paths:
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -193,7 +193,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
@ -202,13 +202,15 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
example: leave
required:
- membership
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
@ -221,27 +223,20 @@ paths:
- type
- depth
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
}
required: true
responses:
200:
"200":
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
@ -249,4 +244,23 @@ paths:
title: Empty Object
description: An empty object.
examples:
application/json: [200, {}]
response:
value: [
200,
{}
]
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

69
data/api/server-server/leaving-v2.yaml
View file

@ -12,21 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Leave Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Leave Room API
version: 1.0.0
paths:
# Note: there is no v2 of make_leave (yet)
"/send_leave/{roomId}/{eventId}":
@ -55,20 +44,21 @@ paths:
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
type: string
description: The event ID for the leave event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
@ -79,7 +69,7 @@ paths:
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
example: matrix.org
origin_server_ts:
type: integer
format: int64
@ -88,7 +78,7 @@ paths:
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
@ -97,13 +87,15 @@ paths:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
example: leave
required:
- membership
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
@ -127,14 +119,33 @@ paths:
"membership": "leave"
}
}
required: true
responses:
200:
"200":
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
content:
application/json:
schema:
type: object
title: Empty Object
description: An empty object.
examples:
application/json: {}
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v2
components:
securitySchemes:
$ref: definitions/security.yaml

54
data/api/server-server/openid.yaml
View file

@ -12,19 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation OpenID API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
title: Matrix Federation OpenID API
version: 1.0.0
paths:
"/openid/userinfo":
/openid/userinfo:
get:
summary: Exchange an OpenID token for user information
description: |-
@ -35,15 +28,16 @@ paths:
parameters:
- in: query
name: access_token
type: string
description: |-
The OpenID access token to get information about the owner for.
description: The OpenID access token to get information about the owner for.
required: true
x-example: SomeT0kenHere
example: SomeT0kenHere
schema:
type: string
responses:
200:
description: |-
Information about the user who generated the OpenID access token.
"200":
description: Information about the user who generated the OpenID access token.
content:
application/json:
schema:
type: object
properties:
@ -51,13 +45,29 @@ paths:
type: string
description: The Matrix User ID who generated the token.
example: "@alice:example.com"
required: ['sub']
401:
required:
- sub
"401":
description: The token was not recognized or has expired.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Access token unknown or expired"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1

103
data/api/server-server/public_rooms.yaml
View file

@ -11,21 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Public Rooms API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Public Rooms API
version: 1.0.0
paths:
"/publicRooms":
/publicRooms:
get:
summary: Get all the public rooms for a homeserver
description: |-
@ -38,36 +29,41 @@ paths:
parameters:
- in: query
name: limit
description: The maximum number of rooms to return. Defaults to 0 (no limit).
example: 10
schema:
type: integer
description: |-
The maximum number of rooms to return. Defaults to 0 (no limit).
x-example: 10
- in: query
name: since
type: string
description: |-
A pagination token from a previous call to this endpoint to fetch more
rooms.
x-example: "GetMoreRoomsTokenHere"
example: GetMoreRoomsTokenHere
schema:
type: string
- in: query
name: include_all_networks
type: boolean
description: |-
Whether or not to include all networks/protocols defined by application
services on the homeserver. Defaults to false.
x-example: false
example: false
schema:
type: boolean
- in: query
name: third_party_instance_id
type: string
description: |-
The specific third-party network/protocol to request from the homeserver.
Can only be used if `include_all_networks` is false.
x-example: "irc"
responses:
200:
description: The public room list for the homeserver.
example: irc
schema:
$ref: "../client-server/definitions/public_rooms_response.yaml"
type: string
responses:
"200":
description: The public room list for the homeserver.
content:
application/json:
schema:
$ref: ../client-server/definitions/public_rooms_response.yaml
post:
summary: Gets the public rooms on the server with optional filter.
description: |-
@ -81,19 +77,15 @@ paths:
operationId: queryPublicRooms
security:
- signedRequest: []
parameters:
- in: body
name: body
required: true
description: |-
Options for which rooms to return, or empty object to use defaults.
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: |-
Limit the number of results returned.
description: Limit the number of results returned.
since:
type: string
description: |-
@ -103,9 +95,8 @@ paths:
rather than via an explicit flag.
filter:
type: object
title: "Filter"
description: |-
Filter to apply to the results.
title: Filter
description: Filter to apply to the results.
properties:
generic_search_term:
type: string
@ -133,31 +124,39 @@ paths:
description: |-
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
example: "irc"
example: irc
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"room_types": [null, "m.space"]
"room_types": [
null,
"m.space"
]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
description: Options for which rooms to return, or empty object to use defaults.
required: true
responses:
200:
"200":
description: A list of the rooms on the server.
content:
application/json:
schema:
type: object
description: A list of the rooms on the server.
required: ["chunk"]
required:
- chunk
properties:
chunk:
title: "PublicRoomsChunks"
title: PublicRoomsChunks
type: array
description: A paginated chunk of public rooms.
items:
allOf:
- $ref: "../client-server/definitions/public_rooms_chunk.yaml"
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
- type: object
properties:
# Override description of join_rule
@ -186,7 +185,8 @@ paths:
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
application/json: {
response:
value: {
"chunk": [
{
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
@ -204,3 +204,18 @@ paths:
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

110
data/api/server-server/query.yaml
View file

@ -12,19 +12,10 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Federation Query API
version: 1.0.0
paths:
"/query/{queryType}":
get:
@ -39,15 +30,16 @@ paths:
parameters:
- in: path
name: queryType
type: string
description: The type of query to make
required: true
x-example: profile
example: profile
schema:
type: string
responses:
200:
description: |-
The query response. The schema varies depending on the query being made.
"/query/directory":
"200":
description: The query response. The schema varies depending on the query being
made.
/query/directory:
get:
summary: Query for the room ID and resident homeservers for a room alias
description: |-
@ -63,21 +55,24 @@ paths:
parameters:
- in: query
name: room_alias
type: string
description: The room alias to query.
required: true
x-example: "#room_alias:example.org"
example: "#room_alias:example.org"
schema:
type: string
responses:
200:
description: |-
The corresponding room ID and list of known resident homeservers for the room.
"200":
description: The corresponding room ID and list of known resident homeservers
for the room.
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The room ID mapped to the queried room alias.
x-example: "!roomid1234:example.org"
example: "!roomid1234:example.org"
servers:
type: array
description: |-
@ -86,27 +81,31 @@ paths:
items:
type: string
required:
- "room_id"
- "servers"
- room_id
- servers
examples:
application/json: {
response:
value: {
"room_id": "!roomid1234:example.org",
"servers": [
"example.org",
"example.com",
"another.example.com:8449",
"another.example.com:8449"
]
}
404:
"404":
description: The room alias was not found.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias not found."
}
"/query/profile":
/query/profile:
get:
summary: Query for profile information about a given user
description: |-
@ -122,20 +121,24 @@ paths:
parameters:
- in: query
name: user_id
type: string
description: The user ID to query.
required: true
x-example: "@someone:example.org"
example: "@someone:example.org"
schema:
type: string
- in: query
name: field
type: string
enum: ['displayname', 'avatar_url']
description: |-
The field to query. If specified, the server will only return the given field
in the response. If not specified, the server will return the full profile for
the user.
schema:
type: string
enum:
- displayname
- avatar_url
responses:
200:
"200":
description: |-
The profile for the user. If a `field` is specified in the request, only the
matching field should be included in the response. If no `field` was specified,
@ -144,6 +147,8 @@ paths:
If the user does not have a particular field set on their profile, the server
should exclude it from the response body or give it the value `null`.
content:
application/json:
schema:
type: object
properties:
@ -152,24 +157,43 @@ paths:
description: |-
The display name of the user. May be omitted if the user does not have a
display name set.
x-example: "John Doe"
example: John Doe
avatar_url:
type: string
description: |-
The avatar URL for the user's avatar. May be omitted if the user does not
have an avatar set.
x-example: "mxc://matrix.org/MyC00lAvatar"
example: mxc://matrix.org/MyC00lAvatar
examples:
application/json: {
response:
value: {
"displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
}
404:
"404":
description: The user does not exist or does not have a profile.
content:
application/json:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
$ref: ../client-server/definitions/errors/error.yaml
examples:
application/json: {
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "User does not exist."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

Some files were not shown because too many files have changed in this diff Show more